geogebra-mcp

geogebra-mcp

一个 MCP 服务，可让 AI（Claude Desktop、Claude Code、Cursor，……）直接在 GeoGebra® Calculator 上绘制和编辑平面几何图形（https://www.geogebra.org/calculator）。

与 GeoGebra AutoDraw AI 扩展的复制粘贴工作流不同，这里的 AI 会循环操作：运行命令、读取错误和图形状态、验证性质、查看截图并自行修正图形；也可以根据要求编辑图形（“H 必须是从 A 向下作的垂足”）。

_{使用 GeoGebra® 制作 — https://www.geogebra.org}

非官方项目，与 GeoGebra GmbH 无关，也未获得其认可。请参阅许可与 GeoGebra。

工作原理

AI client ──MCP (stdio)──► geogebra-mcp ──Playwright──► Chrome window: geogebra.org/calculator
                                                            └─ window.ggbApplet (GeoGebra JS API)

• 首次调用工具时，服务会在 GeoGebra Calculator 中打开一个 Chrome（或 Edge）窗口。用户可以观看图形绘制过程，也可以手动拖动和编辑图形。
• 工具通过 page.evaluate 在页面中调用 GeoGebra JS API（ggbApplet）——不会模拟点击。
• 命令通过 asyncEvalCommandGetLabels 运行，该函数会按需加载 GeoGebra 模块，因此证明器和脚本命令（AreCollinear、Incircle、TriangleCenter、ClosestPoint(line, point)……）都能使用。
• GeoGebra 只会用 null 表示命令失败，因此服务会自行提供诊断信息（未知名称、未知命令、括号不匹配、已知问题）和警告（结果未定义、保留名称、两点交点未指定索引）。
• 如果窗口被关闭或重新加载，下次调用工具时会重新打开窗口，并恢复最后已知的图形。
• 由于 ggbApplet.undo() 不会撤销 API 命令，因此撤销由服务管理（XML 历史记录）。

工具

工具	用途
ggb_run_commands	按顺序运行命令；返回每条命令的结果、创建／移除的对象、警告和失败提示。给已有名称赋值会重新定义该对象。
ggb_get_state	获取对象的类型、定义、值、坐标、可见性、dependsOn / usedBy。
ggb_screenshot	获取绘图区（或整个窗口）的 PNG 截图，用于目视检查。
ggb_evaluate	计算表达式而不添加对象（Angle(B, A, C)、AreCollinear(A, H, O)……）。
ggb_set_style	设置颜色、可见性、标签、标题、粗细、线条样式、点大小、填充和固定状态。
ggb_delete	删除对象（及其依赖对象）。
ggb_clear	开始绘制新图形。
ggb_undo	撤销通过服务进行的更改。
ggb_snapshot	保存／恢复／列出具名版本。
ggb_fit_view	将所有可见点和圆适配到视图中（1:1 比例），并切换坐标轴／网格。
ggb_export	保存为 .ggb 或 .png。

此外还有：资源 geogebra://rules（作图规则）、资源 geogebra://commands（命令目录）、提示词 draw_geometry_problem。

设置

要求：Node.js ≥ 20，以及 Google Chrome 或 Microsoft Edge（否则运行 npx playwright install chromium）。

Claude Code（插件）

claude plugin marketplace add haison8x/geogebra-mcp
claude plugin install geogebra-mcp@geogebra-tools

之后，该服务会在 /mcp 中显示为 plugin:geogebra-mcp:geogebra。之后可使用 claude plugin update geogebra-mcp@geogebra-tools 更新。

Claude Code（不使用插件）

claude mcp add geogebra -- npx -y geogebra-mcp

Claude Desktop、Cursor 和其他 MCP 客户端

编辑 claude_desktop_config.json（设置 → 开发者 → 编辑配置），或编辑客户端的 MCP 配置：

{
  "mcpServers": {
    "geogebra": {
      "command": "npx",
      "args": ["-y", "geogebra-mcp"]
    }
  }
}

然后重启客户端，并尝试提出例如以下请求：“绘制内接于圆 (O) 的三角形 ABC，作高 AH，M 为 BC 的中点。”

从源代码运行

git clone https://github.com/haison8x/geogebra-mcp.git
cd geogebra-mcp
npm install
npm run build
claude mcp add geogebra -- node /path/to/geogebra-mcp/dist/index.js

配置（环境变量）

变量	默认值	含义
GGB_BROWSER	try chrome, msedge, then Playwright Chromium	浏览器通道
GGB_HEADLESS	0	设为 1 可在无窗口模式下运行（用于测试）
GGB_PROFILE_DIR	~/.geogebra-mcp/profile	浏览器配置文件（保留 GeoGebra 登录状态）。每个配置文件对应一个服务实例。
GGB_URL	https://www.geogebra.org/calculator	要打开的页面

开发

发布：更新 package.json、.claude-plugin/plugin.json、.claude-plugin/marketplace.json、server.json（两个 version 字段）中的版本，以及 .mcp.json 中固定的版本。然后推送、运行 npm publish、mcp-publisher publish，并创建 GitHub 发布版本。

npm run build
npm run smoke              # end-to-end test through a real MCP client (headless)
npm run smoke -- --headed  # same, with a visible window

注意事项

• 快照和撤销历史记录在服务运行期间保存在内存中。

许可证与 GeoGebra

• 本仓库中的代码采用 MIT 许可证（LICENSE）。该许可证不涵盖 GeoGebra。
• GeoGebra® 是 GeoGebra GmbH 的注册商标。本项目独立开发，不包含任何 GeoGebra 软件；它会驱动你在 geogebra.org 上使用自己的浏览器，因此你对 GeoGebra 的使用受 GeoGebra 许可证约束。
• GeoGebra 可免费用于非商业用途。商业用途（付费材料、培训、服务……）需要获得 GeoGebra 的许可（[email protected]）。
• 分享使用此工具制作的图形、图像或 .ggb 文件时，请保留署名“Made with GeoGebra®”及指向 https://www.geogebra.org 的链接。

详情请参阅 NOTICE。