Calculator MCP Server

一个完全符合 Model Context Protocol (MCP) 规范的数学计算服务器。

🔄 版本 1.1.0 重大更新

从 v1.0 到 v1.1.0，我们进行了重大架构改进：

• ✨ 统一工具架构：将 9 个独立工具合并为 1 个智能的 calculate 工具
• 🧠 智能类型识别：工具自动检测表达式类型并执行相应计算
• 📊 双格式输出：支持 Markdown 和 JSON 两种输出格式
• 🛡️ 增强的安全性：改进的输入验证和 AST 解析
• 📝 更好的文档：详细的 docstrings 和使用示例

✨ 特性

• 🧮 单一统一工具：一个 calculate 工具处理所有数学运算
• 🤖 自动类型检测：智能识别基础运算、统计计算、方程求解、批量处理
• 📐 丰富的函数支持：20+ 内置数学函数和统计函数
• 📊 双输出格式：Markdown（人类可读）和 JSON（机器可读）
• 📚 资源系统：数学常数和公式库
• 💡 智能提示：数学问题解决和计算验证助手

🚀 快速开始

安装

# 克隆项目
git clone https://github.com/tengmmvp/Calculator_MCP.git
cd Calculator_MCP

# 安装依赖
pip install -r requirements.txt

# 开发环境安装（可选，升级到最新版本）
pip install -r requirements.txt --upgrade

配置 Claude Desktop

方法 1：使用项目配置文件（推荐）

# 复制配置文件到 Claude 配置目录
cp config/claude_desktop_config.json "%APPDATA%\Claude\claude_desktop_config.json"

方法 2：手动配置

将以下配置添加到 Claude Desktop 配置文件中：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "calculator_mcp": {
      "command": "python",
      "args": ["<PROJECT_PATH>/calculator_mcp/server.py"],
      "env": {
        "PYTHONPATH": "<PROJECT_PATH>"
      },
      "description": "Unified mathematical calculator with expression auto-detection"
    }
  }
}

运行服务器

# 直接运行
python calculator_mcp/server.py

# 开发环境运行（推荐，更好的调试支持）
fastmcp dev calculator_mcp/server.py

📁 项目结构

Calculator_MCP/
├── calculator_mcp/               # 🔧 源代码目录
│   ├── __init__.py               # 包初始化文件
│   └── server.py                 # 主服务器文件（包含所有 MCP 功能）
├── docs/                         # 📚 文档目录
├── config/                       # ⚙️ 配置文件目录
│   └── claude_desktop_config.json # 🖥️ Claude Desktop 配置模板
├── requirements.txt              # 📋 Python 依赖列表
├── pyproject.toml                # 📦 项目配置文件
├── README.md                     # 📖 项目说明文档
├── CHANGELOG.md                  # 📝 版本更新日志
└── .gitignore                    # 🚫 Git 忽略文件规则

🔧 统一计算工具

calculate(expression: str, variable: str = "x", response_format: str = "markdown")

一个智能计算工具，自动识别表达式类型并执行相应计算：

支持的运算类型

基础运算示例：

• 2 + 3 * 4 - 基础算术
• (10 + 5) / 3 - 带括号的运算
• 2**3 - 幂运算（注意：使用 ** 而不是 ^）

数学函数示例：

三角函数：

• sin(pi/2) - 正弦函数
• cos(0) - 余弦函数
• tan(pi/4) - 正切函数

对数函数：

• log(100) - 自然对数
• log10(1000) - 常用对数（以 10 为底）

其他函数：

• sqrt(16) - 平方根
• abs(-5) - 绝对值
• round(3.14159) - 四舍五入
• pow(2, 8) - 幂运算

聚合函数：

• max([1, 5, 3]) - 最大值
• min([1, 5, 3]) - 最小值
• sum([1, 2, 3]) - 求和
• len([1, 2, 3, 4]) - 长度

统计计算示例：

• mean([1,2,3,4,5]) - 平均值
• stdev([1,2,3,4,5]) - 标准差
• median([1,3,5,7,9]) - 中位数

线性方程示例：

• 2x + 3 = 7 - 解方程
• 3*y - 5 = 10 - 使用自定义变量名

批量计算示例：

• 2+3; 4*5; 10/2 - 多个表达式同时计算
• sin(pi/2); cos(0); 2**3 - 混合批量计算

参数说明

• expression (必需): 数学表达式或方程字符串
• variable (可选, 默认 "x"): 线性方程中的变量名
• response_format (可选, 默认 "markdown"):
  • "markdown" - 人类可读格式
  • "json" - 机器可读格式

资源系统

• calculator://constants - 数学常数资源

  • π (Pi): 3.14159265359
  • e (Euler's Number): 2.71828182846
  • φ (Golden Ratio): 1.61803398875
  • √2 (Square Root of 2): 1.41421356237
  • √3 (Square Root of 3): 1.73205080757

• calculator://formulas - 常用数学公式资源

  • 圆的面积：A = πr²
  • 三角形面积：A = ½bh
  • 一元二次方程：x = (-b ± √(b²-4ac)) / 2a
  • 勾股定理：a² + b² = c²
  • 平面距离公式：d = √[(x₂-x₁)² + (y₂-y₁)²]
  • 直线斜率公式：m = (y₂-y₁) / (x₂-x₁)

提示系统

• math_problem_solver(problem: str) - 结构化数学问题解决助手

  • 提供五步法解题框架
  • 包含理解、分析、计算、验证和答案生成步骤

• calculation_checker(calculation: str) - 计算验证和解释工具

  • 验证计算的正确性
  • 提供分步解释和替代方法
  • 识别常见错误和陷阱

💡 使用示例

在 Claude Desktop 中使用

直接在 Claude 中输入数学表达式，工具会自动调用：

用户: 计算 2 + 3 * 4
Claude: 2 + 3 * 4 = 14

用户: 解方程 2x + 3 = 7
Claude: x = 2.0

用户: 计算数组的平均值 mean([1,2,3,4,5])
Claude: 平均值是 3.0

用户: 批量计算 2+3; 4*5; 10/2
Claude:
- 2+3 = 5
- 4*5 = 20
- 10/2 = 5

不同输出格式

Markdown 格式（默认）:

calculate("2 + 3 * 4", response_format="markdown")

返回格式化的 Markdown 文本，便于阅读。

JSON 格式（程序化处理）:

calculate("2 + 3 * 4", response_format="json")

返回结构化的 JSON 数据：

{
  "operation": "expression",
  "expression": "2 + 3 * 4",
  "result": 14.0,
  "timestamp": "2025-12-08T10:30:00.000000",
  "steps": ["计算表达式: 2 + 3 * 4", "结果: 14.0"]
}

实际使用场景

日常计算:

• calculate("15% of 240") - 百分比计算
• calculate("sqrt(169) + 7") - 组合运算
• calculate("2**10") - 大数幂运算

统计分析:

• calculate("mean([85, 90, 78, 92, 88])") - 成绩分析
• calculate("stdev([1,2,3,4,5,6])") - 标准差计算

方程求解:

• calculate("3x - 9 = 0") - 简单方程
• calculate("0.5y + 2.5 = 10", "y") - 自定义变量

批量处理:

• calculate("1*2; 3*4; 5*6; 7*8") - 多个计算
• calculate("sum([1,2,3]); mean([4,5,6]); max([7,8,9])") - 混合统计

📝 许可证

MIT License

📦 安装

从源码安装

git clone https://github.com/tengmmvp/Calculator_MCP.git
cd Calculator_MCP
pip install -e .

本地运行（开发模式）

# 克隆项目
git clone https://github.com/tengmmvp/Calculator_MCP.git
cd Calculator_MCP

# 安装依赖
pip install -r requirements.txt

# 运行服务器
python calculator_mcp/server.py

# 或使用 FastMCP 开发模式（推荐，支持热重载）
fastmcp dev calculator_mcp/server.py

使用 uvx 直接运行（推荐）

# 直接从 GitHub 运行
uvx git+https://github.com/tengmmvp/Calculator_MCP

# 或者指定版本
uvx git+https://github.com/tengmmvp/Calculator_MCP@v1.1.0

# 或者运行命令
uvx git+https://github.com/tengmmvp/Calculator_MCP -- calculator-mcp-server

开发环境安装

git clone https://github.com/tengmmvp/Calculator_MCP.git
cd Calculator_MCP
./scripts/setup-dev.sh

🚀 部署

Docker 部署

docker pull tengmmvp/calculator-mcp-server:latest
docker run -p 8080:8080 tengmmvp/calculator-mcp-server

Claude Desktop 配置

将以下配置添加到 Claude Desktop：

方法 1：使用 uvx 安装的命令

{
  "mcpServers": {
    "calculator_mcp": {
      "command": "uvx",
      "args": ["git+https://github.com/tengmmvp/Calculator_MCP"],
      "description": "Unified mathematical calculator with expression auto-detection"
    }
  }
}

方法 2：使用本地路径

{
  "mcpServers": {
    "calculator_mcp": {
      "command": "python",
      "args": ["<PROJECT_PATH>/calculator_mcp/server.py"],
      "env": {
        "PYTHONPATH": "<PROJECT_PATH>"
      },
      "description": "Unified mathematical calculator with expression auto-detection"
    }
  }
}

注意：

• 方法 1（推荐）：使用 uvx 自动管理依赖，无需手动安装
• 方法 2：请将 <PROJECT_PATH> 替换为项目的实际根目录路径
  • Windows 示例：C:\\Users\\YourName\\Projects\\Calculator_MCP
  • macOS/Linux 示例：/home/yourname/projects/Calculator_MCP
  • 路径使用正斜杠或双反斜杠均可

🎯 功能概览

支持的运算类型

类型	示例	说明
基础运算	2 + 3 * 4	加减乘除、幂运算、取模等
数学函数	sin(pi/2)	三角、对数、指数等函数
统计计算	mean([1,2,3])	均值、中位数、标准差、方差等
方程求解	2x + 3 = 7	一元线性方程求解
批量计算	1+2; 3*4; 5/6	多个表达式同时计算

支持的数学函数（共 20 个）

三角函数：sin, cos, tan 对数函数：log, log10 其他函数：sqrt, abs, round, pow 聚合函数：min, max, sum, len 统计函数：mean, median, mode, stdev, variance

安全特性

• 🔒 AST 安全解析，防止代码注入
• 🛡️ 严格的输入验证
• ⚠️ 零除保护
• 📝 清晰的错误提示