glm-mcp — GLM as a cheap delegate for your AI coding agent

GLM (Zhipu / Z.ai) as a ~10x cheaper delegate for your AI coding agent. Your expensive main model — Claude Opus, Copilot's default, or Codex — orchestrates and reviews; GLM does the actual work, billed on cheap GLM tokens. GLM exposes an Anthropic-compatible /v1/messages endpoint, so it drops into anything that already speaks Anthropic. This repo wraps it as an MCP server with four tools, plus one-command installers for Claude Code, GitHub Copilot, and Codex. The same server powers every edition.

How it works

flowchart TD
    You["You"]
    Main["Main agent (Claude Opus / Copilot / Codex)<br/>orchestrates + reviews"]
    Srv["glm MCP server (stdio)<br/>4 tools"]
    Rt["Router<br/>peak-aware model pick + cost bias"]
    Zai[/"Z.ai Anthropic endpoint<br/>POST /v1/messages"/]
    Loop["glm_agent tool loop<br/>read_file / write_file / edit_file<br/>list_dir / run_bash — on your repo"]
    Led[("usage.jsonl<br/>every GLM call: model + tokens")]

    Repo[("your repo")]

    You --> Main -->|"glm_agent(task, workdir)"| Srv
    Srv --> Rt --> Zai
    Zai -->|"tool calls"| Loop
    Loop -->|"tool results"| Zai
    Loop -->|"reads / writes / runs"| Repo
    Zai --> Led
    Srv -->|"summary + GLM STATS<br/>(model, tokens, est. cost)"| Main
    Main -->|"review · diff · revert"| You

Plain-English walkthrough:

1. You ask the main agent for work.
2. The main agent delegates via glm_agent — it passes a goal plus an absolute workdir.
3. The server's router picks a GLM model (peak-aware) and calls the Z.ai /v1/messages endpoint; the cost bias keeps GLM the default.
4. GLM runs its own agent loop (read_file / write_file / edit_file / list_dir / run_bash) directly against your repo, then stops with a summary.
5. The server returns a concise summary + a GLM STATS block (model, tokens, est. cost) to the main agent.
6. The main agent reviews; every GLM call is also appended to the usage.jsonl ledger.

Token economics. Delegated work bills GLM tokens (~10x cheaper). The main model only pays for orchestration + review. A near-100% GLM share requires the full-GLM launcher (claude/glm-code.mjs), because a hybrid main agent always carries per-turn session context — that context is the floor on its token share.

The four tools

Live progress. glm_agent streams MCP progress notifications while it runs — current iteration, token count, and tok/s — shown live in Claude Code and mapped to tool.execution_progress in VS Code Copilot. This heartbeat also keeps long calls alive on clients that reset their timeout on progress, and cancelling a run stops GLM promptly (partial changes are shown and revertable). max_tokens defaults to auto (uncapped/generous; the orchestrating agent may pass a number to cap a call). The server uses an idle/stall timeout (GLM_STALL_TIMEOUT_MS, 2 min), so an actively-streaming turn is never cut off. If a very long run is still cancelled by your client's tool-call timeout, raise it with MCP_TOOL_TIMEOUT / CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

Install

(a) Claude Code

npx glm-mcp-claude --key YOUR_ZAI_KEY

Installs globally by default (user-scoped): the MCP server, a full-tool glm subagent, a PreToolUse auto-routing hook, and an optional glm-code full-GLM launcher. Restart Claude Code, then run glm_status to confirm api_key_loaded: true. Full details: claude/README.md.

(b) GitHub Copilot / VS Code

npx glm-mcp-copilot --key YOUR_ZAI_KEY            # current workspace
npx glm-mcp-copilot --global --key YOUR_ZAI_KEY   # every workspace

Installs the MCP server in agent mode, a GLM custom agent (subagent), a PreToolUse auto-routing hook, and delegation instructions files. Reload the VS Code window, open Copilot Chat in Agent mode, start the glm server. Full details: copilot/README.md.

(c) Codex

Install the published Codex package:

npx glm-mcp-codex --key YOUR_ZAI_KEY

Installs a Codex MCP registration, a glm custom agent, the glm-delegate skill, and an advisory UserPromptSubmit/PreToolUse hook. The config gives GLM tools a 30-minute timeout and prompts before mutating calls. Restart Codex, review the hook with /hooks, and run glm_status. Full details: codex/README.md.

(d) Any MCP client / Glama / Docker

The standalone glm-mcp package — no installer needed for Cursor, Windsurf, Claude Desktop, Glama, etc.:

{
  "mcpServers": {
    "glm": {
      "command": "npx",
      "args": ["-y", "glm-mcp"],
      "env": { "GLM_API_KEY": "YOUR_ZAI_KEY" }
    }
  }
}

For containers, the repo-root Dockerfile runs the same server:

docker build -t glm-mcp .
docker run --rm -i -e GLM_API_KEY=YOUR_ZAI_KEY glm-mcp

The server boots and answers MCP introspection without a key — set GLM_API_KEY only for actual GLM calls.

Editions at a glance

Parity. All three editions expose the same four tools and a subagent while using the same server underneath. Codex uses its native custom-agent, skill, and hook surfaces; its hook is advisory only and must be trusted by the user. Only Claude ships the standalone glm-code full-GLM launcher.

Configuration

All knobs live in .env (git-ignored). Location per edition: Claude ~/.claude/glm-mcp/.env (set during install); Copilot ~/.glm-mcp/glm-mcp/.env; Codex ~/.codex/glm-mcp/.env. Codex sets tool_timeout_sec = 1800 because its default MCP tool timeout is 60 seconds. Full reference with comments: claude/glm-mcp/.env.example.

Peak-aware routing & cost

China peak window is 14:00–18:00 (UTC+8). The glm-5.x family carries a surcharge at peak (~3x peak / ~2x off-peak), so when auto lands on a glm-5.x model at peak the router routes less work to GLM; if you list a no-surcharge model (e.g. GLM_PEAK_MODEL=glm-5.2,glm-4.7) the router prefers it at peak and GLM stays fine to use. The cost bias keeps GLM the default either way — even at peak it is cheaper than the main model.

What stays on the main model: sensitive / secret code, vision input, parallel fan-out,

128K context, latency-tight loops, and heavy dependent tool-loops (the router's hard overrides).

Proof it's really GLM

• usage.jsonl ledger — every GLM call is appended on disk with model + input_tokens + output_tokens. Claude: ~/.claude/glm-mcp/usage.jsonl; Copilot: ~/.glm-mcp/glm-mcp/usage.jsonl. Independent of the Z.ai dashboard.
• glm_status — prints the cumulative ledger totals (calls, tokens, per-model counts).
• === GLM STATS === block — printed after every glm_agent run: model, tokens delegated, iterations, files changed, est. cost vs Opus.

If the ledger is empty, GLM was never called — the work ran on the main model.

Oversight & safety

• dry_run: true on glm_agent — GLM proposes a full diff and writes nothing; approve before applying.
• Git checkpoint revert line — printed after every real glm_agent run (when the workdir is a git repo), so you can undo in one command.
• Key isolation — GLM_API_KEY lives only in the git-ignored .env; it is never baked into the npm packages (scripts/publish-server.mjs scans every pack for .env / usage.jsonl / node_modules and fails loudly).
• Data residency — GLM traffic goes to Z.ai servers in China. Keep secrets and regulated code on the main model; the router's sensitive flag forces it there.

Development / CI

CI (see .github/workflows/ci.yml) runs: syntax checks on the server and every installer/hook/script, the keyless stdio smoke (scripts/smoke-stdio.mjs) that asserts the four-tool MCP handshake with no key on disk, a Docker introspection test (initialize piped into the built image), and an npm-pack secret scan (scripts/publish-server.mjs). PRs welcome — see CONTRIBUTING.md.

License

MIT © djerok · Canonical repo: https://github.com/djerok/glm-mcp