Enhanced GeoGebra MCP

English | 简体中文

Local stdio MCP server for a self-hosted GeoGebra Web bundle.

enhanced-geogebra-mcp wraps a modified GeoGebra 5.0 Web bundle under geogebra/. At runtime it starts a localhost-only static asset server, launches headless Chromium with Playwright, loads public/harness.html, obtains the GeoGebra JavaScript API through GGBApplet.appletOnLoad, and exposes a stdio MCP server.

What Is Enhanced

The bundled applet is expected to expose evalCommandResult(command), a modified API added to the GeoGebra runtime. ggb_eval_command uses that method directly.

Plain evalCommand only reports whether a command was accepted. evalCommandResult returns structured command feedback:

• ok: whether the command succeeded.
• result: command result text returned by the applet.
• labels: labels created by the command.
• error: command error text when execution fails.
• objectCount: construction object count after execution.
• apiMethod: the runtime method used by the server.

There is no fallback to evalCommand. If evalCommandResult is not present in the loaded bundle, command evaluation fails.

Command Feedback Flow

flowchart LR
  A["Choose construction command"] --> B["ggb_query_commands<br/>GeoGebra 5.0 reference"]
  B --> C["ggb_eval_command<br/>call evalCommandResult"]
  C --> D{"Command feedback"}
  D -->|"ok"| E["Use labels/result"]
  D -->|"error"| F["Revise command"]
  F --> B
  E --> G["ggb_get_objects / ggb_export_image<br/>verify construction"]

ReAct Comparison

The main difference is where command observation is produced. A conventional GeoGebra MCP wrapper built around evalCommand usually needs a follow-up inspection step to infer what changed. This package returns command-level observation from ggb_eval_command itself.

For LLM-driven construction loops, the practical advantages are:

• Command execution results add useful context immediately after each action.
• Failed commands return error text, giving the model a concrete correction signal and reducing unsupported guesses.

flowchart TD
  subgraph T["Conventional GeoGebra MCP"]
    direction LR
    T1["Thought<br/>choose command"] --> T2["Action<br/>evalCommand"]
    T2 --> T3["Limited feedback<br/>accepted / rejected"]
    T3 --> T4["Extra inspection<br/>objects / XML / image"]
    T4 --> T5["Infer result, labels, or error"]
  end

  T5 --> V["VS"]

  subgraph E["enhanced-geogebra-mcp"]
    direction LR
    E1["Thought<br/>choose command"] --> E2["Action<br/>ggb_eval_command"]
    E2 --> E3["Execution feedback<br/>ok + result + labels"]
    E3 --> E4["Error feedback<br/>concrete message on failure"]
    E4 --> E5["Revise command with more context"]
  end

  V --> E1

GeoGebra 5.0 Scope

The bundled runtime is GeoGebra 5.0. Commands passed to ggb_eval_command should use GeoGebra 5.0 command names, syntax, and signatures. Use ggb_query_commands when command syntax is uncertain.

Requirements

• Node.js 20 or newer.
• npm or npx.
• An MCP client that supports stdio servers.
• Chromium, either installed by Playwright or provided through an existing Chrome/Chromium executable.
• The modified GeoGebra 5.0 runtime that exposes evalCommandResult. The npm package includes this runtime under geogebra/.

Distribution

This package is released under the MIT license and is intended for npm distribution as enhanced-geogebra-mcp.

This project is not affiliated with GeoGebra. The bundled runtime targets GeoGebra 5.0; command syntax, command reference data, and runtime behavior should stay aligned with that version.

Security And Network

• The MCP server communicates over stdio.
• GeoGebra assets are served from a localhost-only static asset server.
• Browser execution is handled by Playwright and Chromium.
• Browser requests to non-local URLs are blocked by default.
• --allow-external-network explicitly allows non-local browser requests.
• Large state payloads can be returned as MCP resources when they exceed --max-inline-chars.

Known Limitations

• Command syntax is scoped to GeoGebra 5.0.
• Commands should use English GeoGebra input-bar names.
• The server needs a working Chromium runtime.

Versioning And Compatibility

• The npm package version tracks the MCP wrapper.
• The bundled GeoGebra runtime is currently GeoGebra 5.0.
• The bundled command reference is expected to match GeoGebra 5.0 syntax.
• Runtime or API changes that affect evalCommandResult should be documented in CHANGELOG.md.

Install From npm

After the package is published to npm, it can be used directly with npx:

npx -y enhanced-geogebra-mcp --help

MCP client config example:

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

It can also be installed globally:

npm install -g enhanced-geogebra-mcp
enhanced-geogebra-mcp --help

Global install config example:

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

The server uses Playwright to launch Chromium. If no compatible Chromium is available, install one:

npx playwright install chromium

Or point the server at an existing Chrome/Chromium executable with GEOGEBRA_MCP_BROWSER_EXECUTABLE or --browser-executable-path.

Install From Source

npm install
npx playwright install chromium
npm run build

Run As MCP Stdio Server

npm run build
node dist/index.js

Client config example:

{
  "mcpServers": {
    "enhanced-geogebra": {
      "command": "node",
      "args": ["/absolute/path/to/enhanced-geogebra-mcp/dist/index.js"]
    }
  }
}

After packaging:

npm run pack:local

The package exposes an enhanced-geogebra-mcp binary.

Tools

• ggb_create_session: create a headless GeoGebra applet session.
• ggb_eval_command: evaluate English GeoGebra input-bar commands through the bundled applet's evalCommandResult API. The payload includes ok, result, labels, error, objectCount, and apiMethod. This package expects that modified API to exist.
• ggb_query_commands: search the bundled GeoGebra command reference by name, syntax, examples, tags, or scope.
• ggb_eval_cas: evaluate a CAS expression.
• ggb_get_objects: list construction objects and compact metadata.
• ggb_get_state: return XML, base64 .ggb, or fileJSON state.
• ggb_set_state: load XML, base64 .ggb, or fileJSON state.
• ggb_export_image: export PNG, SVG, or screenshot.
• ggb_set_view: set common view options.
• ggb_reset: clear or reset the construction.
• ggb_close_session: close a browser-backed session.
• ggb_list_sessions: list active sessions.

Options

enhanced-geogebra-mcp --help

Notable options:

• --geogebra-root <path>: use a different GeoGebra bundle root.
• --asset-port <port>: pin the internal localhost asset server port.
• --browser-executable-path <path>: use an existing Chrome/Chromium executable.
• --allow-external-network: allow the browser to load non-local URLs. Default is blocked.
• --max-inline-chars <count>: return larger payloads as MCP resources.

You can also set GEOGEBRA_MCP_BROWSER_EXECUTABLE=/path/to/chrome-or-chromium when Playwright's bundled Chromium is not installed.

Smoke Checks

npm run smoke:harness
npm run smoke:mcp

smoke:harness tests the local asset server plus browser runtime directly. smoke:mcp builds the package, starts the stdio MCP server as a child process, and calls the core tools through an MCP client.