GeoGebra MCP Server

让 Claude Code、Codex 和其他 MCP 客户端操控 GeoGebra——绘制几何构造、函数图像、3D 图形、动态机构，保存 .ggb，导出 .png。默认使用 Web Runtime，无需安装 GeoGebra 桌面版。

本项目不是要替代 GeoGebra，而是把 GeoGebra 变成 AI 可以可靠调用的数学可视化后端。

能做什么

Related MCP server: GeoGebra MCP Server

架构

环境要求

• Python 3.10+

• Node.js v16+ 和 npm

• 支持 MCP stdio 的 AI 客户端（Claude Code / Codex / …）

• 首次使用 Web Runtime 需要网络访问 GeoGebra CDN；Puppeteer 会自动下载 Chromium

Windows、macOS、Linux 均可使用。

**可选：**如需使用桌面版后端（GEOGEBRA_BACKEND=desktop），则需要 GeoGebra Classic 6。

默认 Web Runtime

GeoGebra Classic 6 桌面版不再是必需的。 默认情况下，MCP Server 会自动启动 Chromium，加载 GeoGebra 网页版，通过 GeoGebra Apps API 控制绘图。用户无需安装或配置任何 GeoGebra 桌面软件。

GEOGEBRA_BACKEND=auto   # 默认：优先 Web，失败时回落 desktop
GEOGEBRA_BACKEND=web    # 仅使用 Web Runtime
GEOGEBRA_BACKEND=desktop # 仅使用 Classic 6 CDP 桌面版
GEOGEBRA_WEB_HEADLESS=1 # 无头模式（默认）；=0 显示浏览器窗口
GEOGEBRA_WEB_BUNDLE=cdn # 默认：从 GeoGebra CDN 加载；=local 使用离线 bundle

首次使用 Puppeteer 会自动下载 Chromium。
离线模式使用 GeoGebra 官方 web bundle。发布包含该 bundle 的软件包前，请查阅 GeoGebra 许可证。

离线 Web Runtime

下载 GeoGebra Math Apps Bundle 到本地缓存，实现完全离线运行：

# 下载离线 bundle
python scripts/setup_geogebra_web_bundle.py

# 验证 bundle 完整性
python scripts/setup_geogebra_web_bundle.py --check

使用离线模式：

# Windows
$env:GEOGEBRA_BACKEND="web"
$env:GEOGEBRA_WEB_BUNDLE="local"
geogebra-mcp-doctor

# macOS / Linux
GEOGEBRA_BACKEND=web GEOGEBRA_WEB_BUNDLE=local geogebra-mcp-doctor

适合学校机房、离线机器或网络受限环境。普通用户无需下载 bundle，默认 CDN 模式即可。

快速开始

1. 自然语言自动安装（推荐）

仿照 MATLAB Agentic Toolkit 的方式，普通用户可以不手动编辑 MCP JSON/TOML。

git clone https://github.com/123pc/Geogebra_mcp.git
cd Geogebra_mcp

然后在这个目录里启动 Claude Code、Codex 或其他 agent，对它说：

Set up GeoGebra MCP

agent 会根据 AGENTS.md 和 skills/geogebra-setup 的指导运行：

python scripts/setup_geogebra_mcp.py

这个脚本会自动完成：

• 安装 Node 依赖：npm install

• 安装 Python 包：python -m pip install -e .

• 写入 Claude Code 全局 MCP 配置

• 写入 Codex 全局 MCP 配置

• 注册本仓库提供的 skills

• 运行 geogebra-mcp-doctor 做环境诊断

完成后重启 agent，并在任意项目目录中验证：

Use GeoGebra MCP to check status and draw a triangle.

如果只想配置某一个客户端：

python scripts/setup_geogebra_mcp.py --agent claude
python scripts/setup_geogebra_mcp.py --agent codex

2. 手动安装

git clone https://github.com/123pc/Geogebra_mcp.git
cd Geogebra_mcp
npm install                  # Node 依赖（puppeteer，含 Chromium）
python -m pip install -e .   # Python 依赖 + 暴露 CLI 命令

npm install 不可省略——Node 守护进程依赖 puppeteer（自动管理 Chromium 浏览器）。
也可运行 python install_wizard.py 进行交互式安装向导。

3. 环境诊断

geogebra-mcp-doctor
# 如果命令不在 PATH 中，改用：
python -m geogebra_mcp.doctor

预期输出（Web Runtime 默认）：

[OK] python: 3.13.5
[OK] node: v22.17.1
[OK] npm
[OK] daemon_js: .../geogebra_mcp/geogebra_daemon.js
[OK] package_json: .../geogebra_mcp/package.json
[OK] backend: auto
[OK] web_assets: .../geogebra_mcp
[OK] puppeteer: installed
[SKIP] geogebra_install: not required for backend=auto
[SKIP] cdp_port: not required for backend=auto

geogebra_install 和 cdp_port 被跳过是正常的——Web Runtime 不需要 GeoGebra 桌面版。

4. 可选：Desktop 后端（GeoGebra Classic 6 CDP）

仅当设置 GEOGEBRA_BACKEND=desktop 时才需要以下步骤。Web Runtime 用户可跳过。

每次使用前需要以调试模式启动 GeoGebra Classic 6：

Windows： 双击 start_geogebra.bat，或在终端中执行：

CMD：

for /d %v in ("%LOCALAPPDATA%\GeoGebra_6\app-*") do start "" "%~fv\GeoGebra.exe" --remote-debugging-port=9222

PowerShell：

$ggb = Get-ChildItem "$env:LOCALAPPDATA\GeoGebra_6\app-*\GeoGebra.exe" | Sort-Object -Descending | Select-Object -First 1; Start-Process $ggb.FullName "--remote-debugging-port=9222"

macOS：

open -a "GeoGebra Classic 6" --args --remote-debugging-port=9222

Linux：

geogebra-classic --remote-debugging-port=9222

5. 配置 AI 客户端

推荐：运行自动配置脚本（无需手动编辑 JSON）：

python scripts/setup_geogebra_mcp.py

该脚本自动完成：安装依赖 → 写入 MCP 配置 → 注册 skills → 运行诊断。
--agent claude 仅配置 Claude Code，--agent codex 仅配置 Codex。

手动配置： 在你的 MCP 配置文件中加入：

{
  "mcpServers": {
    "geogebra": {
      "command": "python",
      "args": ["-m", "geogebra_mcp.server"]
    }
  }
}

python -m geogebra_mcp.server 在任何目录都能运行，不依赖仓库路径。
pip install -e . 后也可直接用 geogebra-mcp-server（如果 Scripts 目录在 PATH 中）。

Claude Code 用户还需在 settings.json 中添加：

{ "enabledMcpjsonServers": ["geogebra"] }

重启客户端后生效。

MCP 工具

连接与状态

命令执行

视图与外观

输出

给 AI 的调用流程

AI 在处理绘图请求时应遵循以下步骤：

1. 确认输出路径 — 如果用户没指定保存位置，先问「文件保存在哪里？」

2. 检查连接 — geogebra_status

3. 未连接时提示 — Web Runtime 会自动启动 Chromium；Desktop 后端需告知用户双击 start_geogebra.bat 启动 GeoGebra

4. 设置视图 — geogebra_set_view

5. 清空画布（如需） — geogebra_new_construction

6. 发送命令 — 用 geogebra_run_commands 或 geogebra_create_construction

7. 自验收 — geogebra_get_objects，确认对象数 >= 3

8. 动画（如需） — geogebra_set_appearance 使滑块可见 + geogebra_animate 自动播放

9. 保存 — geogebra_save

示例

用自然语言

"画 y=sin(x) 和 y=cos(x)，标出交点，导出到 D:/output/sin_cos.png"

曲柄摇杆机构

{
  "name": "crank_rocker",
  "design": {
    "perspective": "G",
    "commands": [
      "O1=(0,0)", "O2=(6,0)", "alpha=30 deg",
      "A=O1+(2*cos(alpha),2*sin(alpha))",
      "c1=Circle(A,5)", "c2=Circle(O2,4)",
      "B=Intersect(c1,c2,1)",
      "crank=Segment(O1,A)", "coupler=Segment(A,B)",
      "rocker=Segment(B,O2)", "ground=Segment(O1,O2)"
    ],
    "styles": [
      {"label":"alpha","visible":true,"label_visible":true},
      {"label":"crank","color":[1,0,0],"thickness":6},
      {"label":"coupler","color":[0,0.2,1],"thickness":6},
      {"label":"rocker","color":[0,0.7,0.2],"thickness":6},
      {"label":"ground","color":[0,0,0],"thickness":5}
    ],
    "animate": "alpha",
    "speed": 0.5
  },
  "output_dir": "D:/output"
}

推荐使用 ASCII 标签（alpha 而非 α），避免不同客户端间的编码问题。

Skills

仓库附带三套 skill，教 AI 更稳定地使用本 MCP：

环境变量

常见问题

connected: false

Web Runtime（默认）： 检查网络是否能访问 GeoGebra CDN，Puppeteer/Chromium 是否已安装。运行 node scripts/smoke_web_runtime.js 进行诊断。如果 CDN 不可达（如学校机房、离线环境），下载离线 bundle 后设置 GEOGEBRA_WEB_BUNDLE=local 即可（见离线 Web Runtime）。

Desktop 后端（GEOGEBRA_BACKEND=desktop）： GeoGebra 未以调试模式运行。确保已用 --remote-debugging-port=9222 启动（见快速开始第 4 步）。

动画不动

检查三点：

1. 是否创建了角度滑块（alpha=30 deg）

2. 运动点是否依赖滑块（A=O+(2*cos(alpha),2*sin(alpha))）

3. 是否调用了 geogebra_set_appearance 使滑块可见 + geogebra_animate(label="alpha", animate=true)

4. 使用 geogebra_create_construction 可自动处理以上步骤

AI 画的图和实际不符 / 空白

让 AI 调用 geogebra_get_objects 自验收。如果对象数为 0，AI 应重试而非声称"完成"。

已经打开的 GeoGebra 能接管吗？

**Desktop 后端：**不能。必须关闭后以 --remote-debugging-port=9222 重新启动。Web Runtime 不受此限制，它会自动启动独立的 Chromium 实例。

能在 macOS / Linux 上用吗？

可以。三平台均已适配。

为什么要用 alpha 而非 α？

希腊字母在部分客户端、终端或 JSON 日志中可能出现编码异常。推荐默认使用 ASCII 名称以提高普适性。

更新

在项目目录下运行：

python update.py

该脚本自动执行 git pull → npm install → pip install -e . → 同步 MCP 配置和 skills，无需重新 clone。

开发

# 运行测试
python -m pytest -q                     # Python (64 tests)
node tests/test_daemon_protocol.js      # Node (27 tests)

# Web Runtime 冒烟测试
node scripts/smoke_web_runtime.js                    # CDN 模式
GEOGEBRA_WEB_BUNDLE=local node scripts/smoke_web_runtime.js  # 离线模式

# 离线 bundle 管理
python scripts/setup_geogebra_web_bundle.py          # 下载
python scripts/setup_geogebra_web_bundle.py --check  # 验证

# 构建 wheel
python -m build --wheel

贡献

欢迎所有形式的贡献！

• 在 Issues 中报告 bug 或提出功能建议

• 提交 Pull Request 改进代码、文档或 skill

• 测试并适配更多 AI 客户端（Codex、DeepSeek TUI 等）

• 分享你用它绘制的有趣构造

当前适配状态

许可证

MIT © 2026 GeoGebra MCP contributors