How do I use zai-mcp-plus?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zai-mcp-plus Diagnose this error screenshot and suggest a fix." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

zai-mcp-plus

by peamed

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

zai-mcp-plus

基于 @z_ai/mcp-server（Z.AI 视觉理解 MCP Server，Apache-2.0）的本地增强版，主要解决原版无法对接自定义 OpenAI 兼容接口的问题。

项目路径：/path/to/zai-mcp-plus 启动命令：node /path/to/zai-mcp-plus/build/index.js

基于什么修改

基线版本：npm 包 @z_ai/mcp-server@0.1.4（Z.AI 出品，Apache-2.0）。
修改方式：直接在该版本发布包的 build/（已编译代码）基础上修改，未重新走 TypeScript 编译；package.json 版本号标记为 0.1.4-plus 以示区分。
未改动：8 个视觉工具的定义、prompt、以及发给模型的请求体结构均保持原版不变。

Related MCP server: SiliconFlow-Vision-MCP

改动了哪些功能

在原版只支持官方 ZAI / ZHIPU 平台、且不暴露自定义 endpoint 的基础上，新增 / 修复了以下功能：

自定义接口地址：支持通过环境变量配置任意符合 OpenAI 规范的多模态接口地址，不再写死官方域名。
自动补全地址斜杠：接口地址无论是否带结尾 /，都会自动规范为正确请求路径，避免路径拼接导致的 404。
自定义视觉模型：支持通过环境变量指定视觉模型名称（默认 glm-4.6v），可指向后端任意视觉模型。
图片/视频 URL 自动转 base64：传入图片或视频 URL 时，会先在本地下载并转为 base64 再发送，兼容那些自身不抓取远程 URL 的接口。
内联图片兼容：客户端若直接传入 data: URI 或裸 base64 图片，也能正确封装为合法格式，不再误报文件找不到或 image_url 格式错误。
可选调试日志：开启后记录实际发出的图片类型，便于排查黑图 / image_url 报错等问题。

目录结构

zai-mcp-plus/
├── build/                 # 编译后的运行代码（直接由 node 运行）
│   ├── index.js           # MCP Server 入口
│   ├── core/              # 核心：environment / chat-service / file-service / base-image-service
│   ├── tools/             # 8 个视觉工具
│   ├── prompts/
│   └── utils/
├── node_modules/          # 依赖（zod, @modelcontextprotocol/sdk）
├── package.json
└── README.md

安装 / 运行

依赖已安装好。若需重新安装：

cd /path/to/zai-mcp-plus
npm install
node build/index.js        # 由 MCP 客户端以 stdio 方式拉起，无需手动运行

环境变量

变量	必填	默认值	说明
`Z_AI_BASE_URL`	✅（用接口时）	官方域名	接口地址，会自动补 `/`。例如 `http://your-openai-host/v1`
`Z_AI_API_KEY`	✅	—	接口 / 平台 API Key
`Z_AI_VISION_MODEL`	❌	`glm-4.6v`	视觉模型名（需后端真支持视觉）
`Z_AI_VISION_MODEL_TEMPERATURE`	❌	`0.8`	温度
`Z_AI_VISION_MODEL_TOP_P`	❌	`0.6`	top_p
`Z_AI_VISION_MODEL_MAX_TOKENS`	❌	`32768`	最大输出 token
`Z_AI_TIMEOUT`	❌	`300000`	请求超时（ms）
`Z_AI_RETRY_COUNT`	❌	`1`	失败重试次数
`ZAI_DEBUG`	❌	关闭	设为 `1` 写调试日志到 `/tmp/zai_debug.log`

兼容原版：Z_AI_MODE（或 PLATFORM_MODE）仍可设为 ZAI / ZHIPU 选择官方平台；但接接口时直接用 Z_AI_BASE_URL 即可。

客户端配置示例

Claude Code

支持用户级、项目级配置与命令行三种方式。

方式 A：用户级（~/.claude.json）

在 mcpServers 中追加：

{
  "mcpServers": {
    "zai-mcp-plus": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}

方式 B：项目级（.mcp.json）

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "zai-mcp-plus": {
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}

方式 C：命令行

claude mcp add zai-mcp-plus -s user \
  -e Z_AI_BASE_URL=http://your-openai-host/v1 \
  -e Z_AI_VISION_MODEL=你的视觉模型名 \
  -e Z_AI_API_KEY=你的APIKey \
  -- node /path/to/zai-mcp-plus/build/index.js

CodeBuddy

支持用户级与项目级 JSON 配置（无 TOML 配置）。

方式 A：用户级（~/.codebuddy/mcp.json）

{
  "mcpServers": {
    "zai-mcp-plus": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}

方式 B：项目级（.codebuddy/mcp.json）

在项目根目录创建 .codebuddy/mcp.json，内容与方式 A 的 mcpServers 结构一致。

Codex（OpenAI Codex CLI）

Codex 支持两种配置方式，任选其一即可。

方式 A：mcp.json（JSON，格式与 Claude Code 一致）

写入 ~/.codex/mcp.json（或项目级 .codex/mcp.json）：

{
  "mcpServers": {
    "zai-mcp-plus": {
      "command": "node",
      "args": ["/path/to/zai-mcp-plus/build/index.js"],
      "env": {
        "Z_AI_BASE_URL": "http://your-openai-host/v1",
        "Z_AI_VISION_MODEL": "你的视觉模型名",
        "Z_AI_API_KEY": "你的 API Key"
      }
    }
  }
}

方式 B：config.toml（TOML）

写入 ~/.codex/config.toml（或项目级 .codex/config.toml）：

[mcp_servers.zai-mcp-plus]
command = "node"
args = ["/path/to/zai-mcp-plus/build/index.js"]

[mcp_servers.zai-mcp-plus.env]
Z_AI_BASE_URL = "http://your-openai-host/v1"
Z_AI_VISION_MODEL = "你的视觉模型名"
Z_AI_API_KEY = "你的 API Key"

方式 C：命令行添加

codex mcp add zai-mcp-plus \
  --node \
  -- /path/to/zai-mcp-plus/build/index.js \
  -e Z_AI_BASE_URL=http://your-openai-host/v1 \
  -e Z_AI_VISION_MODEL=你的视觉模型名 \
  -e Z_AI_API_KEY=你的APIKey

修改配置后重启客户端让 MCP 重新加载。

提供的工具（与原版一致，共 8 个）

analyze_image：通用图片理解（兜底工具）
ui_to_artifact：UI 截图转前端代码 / prompt / 规格 / 描述
extract_text_from_screenshot：截图 OCR 与文本提取
diagnose_error_screenshot：报错截图诊断与修复建议
understand_technical_diagram：架构图 / 流程图 / UML 理解
analyze_data_visualization：图表数据洞察
ui_diff_check：UI 视觉回归对比
analyze_video：视频内容理解

调用示例（在客户端对话里）：

用 mcp 工具 zai-mcp-plus 的 analyze_image 理解一下 /绝对路径/不登录.png

常见问题排查

1. 启动即报 404 Z_AI_BASE_URL 没带结尾 / 时原版会拼出 .../v1chat/completions。本 fork 已自动补 /，若仍 404 请确认接口路径本身是否就是 .../chat/completions。

2. 报 image_url must be base64-encoded image or a URL 说明发给接口的 image_url 不是合法的 data: URL。本 fork 已对路径 / URL / data: URI / 裸 base64 做了全面兜底；若仍出现，开启 ZAI_DEBUG=1 后看 /tmp/zai_debug.log 里 url_kind 是 data / http / OTHER，据此定位。

3. 模型说"图片是黑的" 先确认源图本身是否正常（本机用图片查看器打开）。本 fork 对本地文件会读成 data:image/png;base64,... 发送。若客户端自身把图读进上下文时渲染成黑块（与 MCP 无关），属于客户端图片预览问题，可让模型改走 MCP 工具、避免客户端直接读图。

4. 只想清掉调试日志 ZAI_DEBUG 不设或设为 0 即可；日志文件在 /tmp/zai_debug.log，可手动删除。

许可

基于 @z_ai/mcp-server 修改，原项目 Apache-2.0。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
mcp-veoOAuth
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
mcp-qwen-imageOAuth
io.github.AceDataCloud
MCP server for Qwen Image 3 AI image generation
AI & Machine Learning Image & Video Processing
1
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

Vison-MCP
Image & Video Processing AI & Machine Learning
Lin-zhibo
A
license
A
quality
D
maintenance
MCP server for vision AI — screenshots to code, OCR, error diagnosis, and image analysis via OpenAI-compatible APIs.
Updated 3 months ago (2026-06-10 18:47 UTC)
8
2
MIT
SiliconFlow-Vision-MCP
Image & Video Processing AI & Machine Learning Developer Tools
klx1204
A
license
Not graded
quality
B
maintenance
An MCP server that provides 8 vision tools for UI screenshot to code, OCR, error diagnosis, diagram understanding, data visualization analysis, UI diff, and image/video analysis, plus model list query, powered by SiliconFlow's multimodal API.
Updated a month ago (2026-08-04 07:49 UTC)
GPL 3.0
glm-vision-mcp
Image & Video Processing AI & Machine Learning
JJChou000
A
license
A
quality
B
maintenance
A drop-in MCP vision server for Zhipu GLM Coding Plan, offering 8 vision tools powered by glm-5v-turbo with smart retry and caching.
Updated 25 days ago (2026-08-21 03:46 UTC)
8
18 npm
1
MIT
vision-mcp
Image & Video Processing AI & Machine Learning
sunqb
F
license
A
quality
C
maintenance
An MCP server for image understanding via OpenAI-compatible vision models, offering tools for OCR, error screenshot diagnosis, technical diagram reading, data visualization analysis, UI-to-code conversion, and UI diff comparison.
Updated a month ago (2026-08-10 03:48 UTC)
7
-

zai-mcp-plus

基于什么修改

改动了哪些功能

目录结构

安装 / 运行

环境变量

客户端配置示例

Claude Code

CodeBuddy

Codex（OpenAI Codex CLI）

提供的工具（与原版一致，共 8 个）

常见问题排查

许可

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Vison-MCP

SiliconFlow-Vision-MCP

glm-vision-mcp

vision-mcp