Fixing GLM-4.7 Image Parsing in Claude Code: Add the Z.ai Vision MCP Server

GLM 4.7 on Claude Code is handicapped without the Z.ai MCP sever. Install it now. Takes less than five minutes.

The Z.ai MCP server allows hassle-free image parsing from within Claude Code

If you are running [Claude Code on GLM-4.7 via Z.ai](http://GLM 4.7 usage), text work is great until you paste a screenshot. Then the model confidently invents details or misses obvious text (which is a no-no). The fix is not a prompt trick. You need the Z.ai Vision MCP server so image analysis runs through MCP instead of the default image path.

In this guide I will show the exact MCP config, a quick verification flow, and a short checklist of gotchas. If you want the full GLM-4.7 setup for Claude Code, see my earlier guide here.

Who this is for

• You already run Claude Code against GLM-4.7 on Z.ai.
• Pasted images are misread or hallucinated.
• You want a minimal, reliable fix without changing your whole setup.

Why images go OFF THE RAILS without the Vision MCP server

Claude Code can call tools through MCP, but direct image pastes do not automatically go through an MCP server. Z.ai’s Vision MCP server exposes dedicated vision tools (OCR, UI analysis, diagram understanding, general image analysis) over MCP. When you paste an image directly, the client transcodes it and sends it to the model interface without invoking that server, so you lose the purpose-built vision tooling and the output goes weird.

Once the Vision MCP server is configured, you can route image analysis through MCP and get consistent, accurate reads. The simplest way is to save the image locally and reference it by filename or path.

The fix: add the Z.ai Vision MCP server to Claude Code

1) Generate (or refresh) your Z.ai API key

You can often reuse the same key you already use for the Anthropic-compatible endpoint, but I recommend creating a fresh key. Older keys may not have the right scope for MCP, which shows up as “invalid key” or silent failures.

2) Make sure your local runtime is up to date

The Vision MCP server is an npx package. Z.ai’s docs currently require Node.js 22+ and recommend the latest server version. If you are seeing odd behaviour, force the latest package (@z_ai/mcp-server@latest) or clear your npx cache.

3) Add the MCP server config for Claude Code

Drop this into your Claude Code MCP config. If you manage MCP servers via the CLI, you can still put the same values into the generated config. Replace your_api_key with your real key.

{
  "mcpServers": {
    "zai-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@z_ai/mcp-server"
      ],
      "env": {
        "Z_AI_API_KEY": "your_api_key",
        "Z_AI_MODE": "ZAI"
      }
    }
  }
}

Tip: Claude Code supports user and project MCP configs. For example, project scope uses .mcp.json at the repo root and user scope uses ~/.claude.json. If you want this available everywhere, use the user scope. If you want it only in a repo, use project scope.

Verify it with a simple image prompt

1. Save a screenshot in your working folder (for example demo.png).
2. Ask: “Describe demo.png and list any visible text.”
3. Look for a vision tool call and a concrete, grounded description.

If you still paste images directly, the client may bypass MCP. For now, reference a file path to be sure the MCP server is used.

The Z.ai Vision MCP server in action

Below, I’m pasting a simple screenshot of the Z.ai homepage to Claude Code.

The image

A pretty basic search box

How Claude Code behaves WITHOUT the Z.ai MCP server

Holy hallucination, Batman! Z.ai needs specsavers.

How Claude Code behaves WITH the Z.ai MCP server

You don’t even need to manually invoke the Vision MCP server. It detects an image pasted onto the prompt and self-invokes out of the box.

Bam, you got it.

Easy as that.

Quick troubleshooting checklist

• Node.js 22+ installed.
• @z_ai/mcp-server updated (use @latest if needed).
• Z_AI_API_KEY set and active.
• Z_AI_MODE set to ZAI.
• If you reused an older key, generate a new one.

Bonus: the same server in Codex

If you are using Codex with MCP, this config gives you the same Z.ai server (and other MCP capabilities beyond vision). Not that you need it, but if you wish to try it out on anything other than Claude Code, at least you have options.

[mcp_servers.zai-mcp]
startup_timeout_sec = 30
type = "stdio"
command = "npx"
args = ["-y", "@z_ai/mcp-server"]
env_vars = ["Z_AI_API_KEY"]
​
[mcp_servers.zai-mcp.env]
Z_AI_MODE = "ZAI"

Related: full GLM-4.7 setup in Claude Code

If you want the broader GLM-4.7 setup (model mapping, wrapper, pricing notes), here is the original guide: https://blog.devgenius.io/claude-code-but-cheaper-glm-4-7-on-z-ai-with-a-tiny-wrapper-9ad98adffc29

References

• Vision MCP Server (Z.ai docs) — Official setup, environment variables, and supported tools. https://docs.z.ai/devpack/mcp/vision-mcp-server
• Claude Code MCP documentation — How to add MCP servers and where configs live. https://code.claude.com/docs/en/mcp
• Model Context Protocol overview — What MCP is and how tools plug in. https://modelcontextprotocol.io/
• Original GLM-4.7 guide — Full Claude Code + Z.ai setup. https://blog.devgenius.io/claude-code-but-cheaper-glm-4-7-on-z-ai-with-a-tiny-wrapper-9ad98adffc29

Liked this guide?

🚀 You’ve been invited to join the GLM Coding Plan! Enjoy full support for Claude Code, Cline, and 10+ top coding tools — starting at just $3/month. Subscribe now and grab the limited-time deal! Link： https://z.ai/subscribe?ic=IIJ5RBCVWO