Calculator

Calculator MCP 服务

一个能够精确执行算术运算的 MCP 服务，让大模型不必在脑中计算。

提供一个工具 calculate，使用手工编写的 AST 允许列表来计算表达式。不使用 eval()、sympy，也不依赖不受限制的依赖项。

2 + 3 * (4 - 1) / 2 ** 2   ->  4.25
sqrt(16) + sin(pi/2)       ->  5.0
123456789 * 987654321      ->  121932631112635269

为什么要开发这个项目

广泛使用的 mcp-server-calculator 包已被弃用（最后一次提交于 2025 年 5 月），并声明依赖 mcp>=1.4.1，却没有设置上限。当 MCP Python SDK 发布 v2 并移除 mcp.server.fastmcp 后，每次通过 uvx …@latest 安装该包都会在导入时崩溃，导致承载它的整个 MCP 代理以及同时运行的所有其他服务都被拖垮。

目前没有维护中的 Python 替代方案。唯一仍在积极维护的 npm 计算器使用 float64 进行计算，因此 123456789 * 987654321 会得到 121932631112635260，误差达 9。对于一个旨在让模型不必亲自进行算术运算的工具而言，这种特性很不理想。

因此，本服务：

• 限制唯一依赖的版本范围（mcp[cli]>=2,<3）——上述故障不会在这里重现；
• 确保任意大小的整数都精确，绝不强制转换为浮点数；
• 限制资源使用量，而不仅是代码执行；详见下文。

安全性

这里有两个问题，而大多数计算器服务只解决了第一个。

代码执行。 使用 ast.parse 解析表达式，并根据明确的节点类型允许列表遍历 AST。Attribute 不在允许列表中，因此 (1).__class__.__bases__ 会被拒绝。只有当 Call 的目标是函数允许列表中的裸名称时，才会对其求值，因此 __import__('os').system(…) 会在任何参数求值之前被拒绝。

资源耗尽。 仅有允许列表仍会放任 9**9**9 通过不受限制的大整数幂运算占用进程数分钟——现有服务在处理该表达式时会卡住超过 5 秒。四项限制可解决这个问题：表达式长度（500 个字符）、嵌套深度（32）、结果大小（4300 位数字，在求幂前检查操作数）以及阶乘参数（1000）。

完整说明见 docs/tech/SAFE-EVALUATION.md。

安装

uvx calc-mcp-server

请固定版本。不要添加 @latest——被本项目替代的包正是因此出问题的。

配置

作为 stdio MCP 服务：

{
  "mcpServers": {
    "calculator": {
      "command": "uvx",
      "args": ["calc-mcp-server"]
    }
  }
}

calculate 工具

参数	类型	描述
expression	str	要计算的表达式

返回字符串形式的结果；如果表达式被拒绝，则返回以 Error: 开头并说明原因的一行文本。该工具绝不会抛出异常，因此，Agent 可以读取并处理错误表达式的说明，而不会导致工具调用失败。

运算符——+ - * / // % **、括号、一元 +/-。^ 也可用作乘方运算符，× · ÷ − 则可作为相应 ASCII 符号的替代形式（语音转文字会生成这些符号）。

常量——pi、e、tau。

函数——abs round min max sqrt exp log log2 log10 sin cos tan asin acos atan atan2 degrees radians hypot floor ceil factorial gcd lcm。

结果——整数运算会返回任意大小的精确整数。浮点数以 12 位有效数字显示，从而消除 IEEE-754 表示误差（0.1 + 0.2 会显示为 0.3，而不是 0.30000000000000004），同时保留远超计算器结果实际用途所需的精度。整数值的浮点数会保留 .0，因此 8 / 2 会显示为 4.0，与精确整数 4 区分开来。

开发

uv sync
uv run pytest tests/ -v
uv run ruff check .
uv run ruff format .

项目指南见 AGENTS.md，完整文档集见 docs/。

许可证

MIT——详见 LICENSE。