Numeratica — financial planning calculations

@numeratica/mcp

一个轻量的 MCP 桥接工具，可将任意 MCP 客户端（Claude Desktop、Cursor、……）连接到 Numeratica 财务规划 API，支持退休蒙特卡洛模拟、税务、RMD、社会保障、Roth 转换等功能。

在 https://docs.numeratica.com 免费获取密钥。

工作原理

本软件包只是一个传输桥接工具，仅此而已。它从 stdin 读取 JSON-RPC，并将每条消息连同作为 bearer token 的 API 密钥转发到托管的 POST /mcp 端点，然后将响应写回 stdout。工具列表和所有结果都直接来自 API，因此桥接工具始终与 API 保持同步，自身不包含任何计算逻辑。密钥仅在 Authorization 标头中发送，绝不会被记录。

• 零运行时依赖（Node ≥ 20 内置的 fetch + node:readline）。
• 开源（MIT）。真正重要的是 API；这里仅负责传输。

安装

无需安装——MCP 客户端会按需通过 npx 运行它。（你也可以运行 npm i -g @numeratica/mcp 来获取 numeratica-mcp 命令。）

步骤 1 — 浏览了解，无需密钥

从这里开始。此配置无需注册，也无需密钥：

{
  "mcpServers": {
    "numeratica": {
      "command": "npx",
      "args": ["-y", "@numeratica/mcp"]
    }
  }
}

将其放入 claude_desktop_config.json（Claude Desktop：Settings → Developer → Edit Config）或 ~/.cursor/mcp.json（Cursor，或项目中的 .cursor/mcp.json），然后 重启客户端。此时会显示全部 76 个工具，你可以询问有哪些工具可用，例如 “Numeratica 有哪些工具？”

没有密钥时，桥接工具会以仅发现模式运行：可以浏览目录，但运行计算时会返回提示你添加密钥的消息。这是预期状态，并非故障。

步骤 2 — 添加密钥以运行计算

在 docs.numeratica.com/get-key 免费获取密钥， 然后添加一行：

{
  "mcpServers": {
    "numeratica": {
      "command": "npx",
      "args": ["-y", "@numeratica/mcp"],
      "env": { "NUMERATICA_API_KEY": "nmr_sk_your_key_here" }
    }
  }
}

重启后，工具即可使用。试试：“为一位 40 岁、计划在 65 岁退休的人运行退休蒙特卡洛模拟。”

配置

变量	必需	默认值	说明
NUMERATICA_API_KEY	运行计算时必需	—	你的密钥。在 docs.numeratica.com/get-key 免费获取。绝不会被记录。省略此项即可在仅发现模式下浏览目录。
NUMERATICA_BASE_URL	否	https://api.numeratica.com	覆盖 API 基础地址（例如用于测试）。

你也可以使用 --key <value> 或 --key=<value> 传入密钥，以替代环境变量，但建议使用 NUMERATICA_API_KEY：命令行中的密钥对机器上的所有用户都可通过 ps 查看，会留在 shell 历史记录中，还会以明文形式存储在 MCP 客户端配置文件里，而人们经常会把这些配置粘贴到问题报告中。若要使用非环境变量的选项，同时避免这三种风险，请使用 --key-file <path>。

链接

• API 文档和参考资料： https://docs.numeratica.com
• 免费获取密钥： https://docs.numeratica.com/get-key

许可证

MIT © Numeratica / Francis Townsend-Merino