mma-mcp

Chinese / 中文版

一个 Model Context Protocol (MCP) 服务器，封装了本地 Wolfram Engine，使 AI 助手（Claude、ChatGPT 等）能够通过 Wolfram 语言执行符号数学、数值分析和数据可视化。

免责声明： 这是一个非官方、独立的个人项目。 它不隶属于 Wolfram Research, Inc.，也不受其赞助、认可或认证。“Wolfram”、“Wolfram Language”、“Wolfram Engine”、“Mathematica”及相关标志是 Wolfram Research 的商标。

本软件不包含任何 Wolfram Engine / Mathematica 二进制文件、激活密钥、许可证文件或其他专有材料。用户必须根据 Wolfram 的许可条款独立获取并合法授权其自己的 Wolfram Engine 或 Mathematica 副本。

本项目的唯一目的是允许已获得许可的个人在 AI 助手的辅助下，在其自己的机器上调用其本地安装的 Wolfram 内核，且在许可允许的范围内使用。 将 Wolfram Engine 的访问权限重新分发给第三方并非本项目的预期用途，且可能违反 Wolfram 的许可条款。

功能特性

• MCP 工具：evaluate（文本）和 evaluate_image（PNG，实验性）——通过两个通用工具实现所有 Wolfram 语言功能

• 传输方式：stdio（本地）和流式 HTTP

• 安全性：内核预处理表达式过滤，支持黑名单/白名单模式及 29 个功能组

• 客户端 RBAC：基于客户端的凭据，以及基于角色的工具和安全策略控制——用于在同一台机器上隔离不同的 AI 客户端

• OAuth 2.1：用于基于 Web 的 MCP 客户端（Claude.ai、ChatGPT）的授权服务器

• 配置驱动：单个 TOML 文件控制所有行为

前置要求

• Python 3.11+

• Wolfram Engine 或 Mathematica（已获得合法授权）

• uv 包管理器

快速开始

# Clone and install
git clone https://github.com/siqiliu-tsinghua/mma-mcp.git
cd mma-mcp
uv sync

# Graphics export dependencies (headless servers only — desktops already have these)
sudo apt-get install -y libfontconfig1 libgl1 libasound2t64 libxkbcommon0 libegl1

# Generate default config
uv run mma-mcp init

# Generate security group files (requires Wolfram kernel, ~1 min)
uv run mma-mcp setup

# Start server (stdio, for local MCP clients)
uv run mma-mcp serve

客户端配置

Claude Code / VS Code (stdio)

添加到你的 .mcp.json：

{
  "mcpServers": {
    "mma-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/mma-mcp", "run", "mma-mcp"]
    }
  }
}

Claude Desktop (stdio)

添加到你的 claude_desktop_config.json（设置 -> 开发者 -> 编辑配置）：

{
  "mcpServers": {
    "mma-mcp": {
      "command": "/path/to/mma-mcp/.venv/bin/mma-mcp"
    }
  }
}

在 macOS/Linux 上，配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json 或 ~/.config/Claude/claude_desktop_config.json。

HTTP 传输

uv run mma-mcp serve --transport http --host 127.0.0.1 --port 8000

配置

所有设置均位于 mma_mcp.toml（或 pyproject.toml 中的 [tool.mma-mcp] 部分）。

uv run mma-mcp init  # generates mma_mcp.toml with comments

关键部分：

安全性

表达式在到达 Wolfram 内核之前会被过滤。符号通过正则表达式提取，并根据活动策略进行检查。

黑名单模式（默认）：阻止危险组（system_exec、文件 I/O、网络、动态评估）。

白名单模式：仅允许来自明确启用组的符号。

29 个功能组（22 个安全 + 7 个危险）涵盖了约 6000 个 Wolfram 语言符号。可从本地内核重新生成：

uv run mma-mcp setup          # required after cloning (generates from your local kernel)
uv run mma-mcp setup --force   # force regeneration (e.g., after Wolfram Engine upgrade)

客户端身份与角色

使用 HTTP 传输时，你可以配置每个客户端的凭据和角色，以隔离连接到同一内核的不同 AI 客户端（例如 Claude 和 ChatGPT）：

# Generate password hash
uv run mma-mcp hash-password

# Generate TOML snippet for a new client
uv run mma-mcp add-client alice --role admin

每个客户端都绑定到一个角色，该角色控制其可以访问的工具、可以使用的 Wolfram 符号以及资源限制（超时、结果大小）。并发客户端通过内核工作池进行隔离——每个工具调用都在具有临时 WL 上下文的独立内核进程中运行。

有关配置详情，请参阅 mma_mcp.toml 中的 [auth] 部分。

开发

# Run tests
uv run pytest tests/ -v

# Inspect MCP tools interactively
uv run mcp dev src/mma_mcp/server.py

CLI 命令

客户端兼容性

许可证

MIT — 仅适用于本仓库中的代码。Wolfram Engine / Mathematica 的使用受 Wolfram Research 自身的许可条款约束。