Numeratica MCP server
✓ VerifiedEnables AI clients to perform deterministic US financial planning calculations including retirement Monte Carlo, taxes, RMDs, and Social Security.
Also known as numeratica/mcp, mcp, @numeratica/mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.5
- Last commit
- Jul 28, 2026
- License
- MIT
What is Numeratica MCP?
Numeratica enables AI clients to perform deterministic US financial planning calculations including retirement Monte Carlo, taxes, RMDs, and Social Security.
Summary generated from the project's README
About Numeratica MCP server
Numeratica provides a specialized bridge for AI clients like Claude Desktop and Cursor to access deterministic US financial planning calculations. This server acts as a transport layer that forwards requests to the hosted Numeratica API, ensuring that all calculation logic remains centralized and accurate. It allows users to perform complex tasks such as retirement Monte Carlo simulations, tax calculations, RMD assessments, Social Security planning, and Roth conversions.
Users can run the server immediately using npx without any initial setup to browse the available tool catalogue in discovery-only mode. To execute actual financial calculations, a NUMERATICA_API_KEY must be provided via an environment variable. The server is designed with zero runtime dependencies, utilizing built-in Node fetch and readline capabilities to maintain a lightweight footprint. It functions as a thin wire between your local MCP client and the remote API endpoint.
What you can do with it
- 1Simulate retirement scenariosAsk the AI to perform a Monte Carlo simulation for a specific retirement age and current age.
- 2Explore available financial toolsUse the discovery-only mode to see the full list of seventy-six available tools without needing an API key.
- 3Calculate complex tax obligationsRequest specific financial planning calculations including taxes, RMDs, and Social Security through the AI interface.
Written from the project's README. Every use case is checked against a quote from it.
How to install Numeratica MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Numeratica MCP in Claude Code
$ claude mcp add --env 'NUMERATICA_API_KEY=<YOUR_NUMERATICA_API_KEY>' mcp -- npx -y @numeratica/mcpInstall Numeratica MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numeratica/mcp"
],
"env": {
"NUMERATICA_API_KEY": "<YOUR_NUMERATICA_API_KEY>"
}
}
}
}Install Numeratica MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@numeratica/mcp"
],
"env": {
"NUMERATICA_API_KEY": "<YOUR_NUMERATICA_API_KEY>"
}
}
}
}Install Numeratica MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@numeratica/mcp"],"env":{"NUMERATICA_API_KEY":"<YOUR_NUMERATICA_API_KEY>"}}'Install Numeratica MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numeratica/mcp"
],
"env": {
"NUMERATICA_API_KEY": "<YOUR_NUMERATICA_API_KEY>"
}
}
}
}Install Numeratica MCP in Codex
$ codex mcp add mcp --env 'NUMERATICA_API_KEY=<YOUR_NUMERATICA_API_KEY>' -- npx -y @numeratica/mcpInstall Numeratica MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@numeratica/mcp"] [mcp_servers.mcp.env] NUMERATICA_API_KEY = "<YOUR_NUMERATICA_API_KEY>"
Install Numeratica MCP in Gemini CLI
$ gemini mcp add -s user -e 'NUMERATICA_API_KEY=<YOUR_NUMERATICA_API_KEY>' mcp npx -- -y @numeratica/mcpInstall Numeratica MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@numeratica/mcp"
],
"env": {
"NUMERATICA_API_KEY": "<YOUR_NUMERATICA_API_KEY>"
}
}
}
}Configuration
NUMERATICA_API_KEYRequiredSecretNumeratica API key (nmr_sk_...). Free self-serve key at https://docs.numeratica.com/get-key
NUMERATICA_BASE_URLOverride the API base URL. Defaults to https://api.numeratica.com; only needed for a staging or self-hosted deployment.
NUMERATICA_TIMEOUT_MSPer-request timeout in milliseconds (default 120000, minimum 1000). Raise it for long-horizon Monte Carlo runs.
| Name | Description | |
|---|---|---|
| NUMERATICA_API_KEY | Numeratica API key (nmr_sk_...). Free self-serve key at https://docs.numeratica.com/get-key | RequiredSecret |
| NUMERATICA_BASE_URL | Override the API base URL. Defaults to https://api.numeratica.com; only needed for a staging or self-hosted deployment. | |
| NUMERATICA_TIMEOUT_MS | Per-request timeout in milliseconds (default 120000, minimum 1000). Raise it for long-horizon Monte Carlo runs. |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenumeratica/mcp is public and reachablegithub.com/numeratica/mcp ↗Pass
- Package names this repository as its source@numeratica/mcp names numeratica/mcp as sourcenpmjs.com/package/@numeratica/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @numeratica/mcpnpmjs.com/package/@numeratica/mcp/v/0.1.5#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-28github.com/numeratica/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @numeratica/mcpPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 100 msPass
README
View on GitHub@numeratica/mcp
A thin MCP bridge that connects any MCP client (Claude Desktop, Cursor, …) to the Numeratica financial-planning API — retirement Monte Carlo, taxes, RMDs, Social Security, Roth conversions, and more.
Get a free key at https://docs.numeratica.com.
How it works
This package is a transport bridge, nothing more. It reads JSON-RPC from stdin and forwards each message to the hosted POST /mcp endpoint with your API key as a bearer token, then writes the response back to stdout. The tool list and all results come straight from the API — so the bridge always stays in sync and ships no calculation logic of its own. Your key is sent only in the Authorization header and is never logged.
- Zero runtime dependencies (Node ≥ 20 built-in
fetch+node:readline). - Open source (MIT). The interesting part is the API; this is just the wire.
Install
No install needed — your MCP client runs it on demand with npx. (You can also npm i -g @numeratica/mcp to get the numeratica-mcp command.)
Step 1 — look around, no key needed
Start here. This config needs no signup and no key:
{
"mcpServers": {
"numeratica": {
"command": "npx",
"args": ["-y", "@numeratica/mcp"]
}
}
}
Put it in claude_desktop_config.json (Claude Desktop: Settings → Developer → Edit
Config) or ~/.cursor/mcp.json (Cursor, or a project .cursor/mcp.json), then
restart the client. All 76 tools appear, and you can ask what's available — "What
Numeratica tools do you have?"
Without a key the bridge runs in discovery-only mode: browsing the catalogue works, running a calculation returns a message telling you to add a key. That's the intended state, not a failure.
Step 2 — add a key to run calculations
Get a free key at docs.numeratica.com/get-key, then add one line:
{
"mcpServers": {
"numeratica": {
"command": "npx",
"args": ["-y", "@numeratica/mcp"],
"env": { "NUMERATICA_API_KEY": "nmr_sk_your_key_here" }
}
}
}
Restart, and the tools are live. Try: "Run a retirement Monte Carlo for a 40-year-old retiring at 65."
Configuration
| Variable | Required | Default | Notes |
|---|---|---|---|
NUMERATICA_API_KEY |
to run calculations | — | Your key. Get one free at docs.numeratica.com/get-key. Never logged. Omit it to browse the catalogue in discovery-only mode. |
NUMERATICA_BASE_URL |
no | https://api.numeratica.com |
Override the API base (e.g. for testing). |
You can also pass the key with --key <value> or --key=<value> instead of the env
var, but prefer NUMERATICA_API_KEY: a key on the command line is visible to
ps for every user on the machine, lands in shell history, and is stored verbatim
in MCP client config files that people routinely paste into issue reports. For a
non-env option that avoids all three, use --key-file <path>.
Links
- API docs & reference: https://docs.numeratica.com
- Get a free key: https://docs.numeratica.com/get-key
License
MIT © Numeratica / Francis Townsend-Merino
Numeratica MCP questions
How do I add Numeratica MCP to Claude Code?
Run claude mcp add --env 'NUMERATICA_API_KEY=<YOUR_NUMERATICA_API_KEY>' mcp -- npx -y @numeratica/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Numeratica MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is my API key secure?
Yes, the key is sent only in the Authorization header and is never logged by the bridge.