智谱AI MCP 使用指南

1. 安装

方法1：使用 uv（推荐）

git clone https://github.com/xiispace/zhipu-mcp.git
cd zhipu-mcp
uv sync

方法2：使用 pip

git clone https://github.com/xiispace/zhipu-mcp.git
cd zhipu-mcp
pip install -e .

2. 配置

2.1 获取API Key

访问 智谱AI开放平台 获取 API Key

2.2 设置环境变量

export ZHIPU_API_KEY="your-api-key-here"

3. 启动服务器

# 默认配置启动 (127.0.0.1:8000/mcp)
uv run zhipu-websearch-mcp

# 自定义配置启动
uv run zhipu-websearch-mcp --host 0.0.0.0 --port 9000 --path /api/mcp

4. 配置MCP客户端

4.1 Claude Desktop 配置

macOS配置文件位置： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows配置文件位置： %APPDATA%\Claude\claude_desktop_config.json

添加配置：

{
  "mcpServers": {
    "zhipu": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

注意：需要先启动MCP服务器，再启动Claude Desktop

4.2 Cursor 配置

在Cursor的MCP设置中添加：

{
  "zhipu": {
    "url": "http://127.0.0.1:8000/mcp"
  }
}

4.3 CoPaw 配置

编辑CoPaw的MCP配置文件：

mcp:
  enabled: true
  server:
    host: 127.0.0.1
    port: 8000
    path: /mcp
  clients:
    - name: zhipu_search
      url: http://127.0.0.1:8000/mcp
      type: http

5. 工具说明

web_search - 网络搜索

参数	类型	必需	默认值	说明
query	string	✅	-	搜索查询内容（建议不超过70字符）
search_engine	string	❌	search_std	搜索引擎类型
search_intent	boolean	❌	false	是否进行搜索意图识别
count	integer	❌	10	返回结果条数（1-50）
search_domain_filter	string	❌	-	白名单域名过滤
search_recency_filter	string	❌	noLimit	时间范围过滤
content_size	string	❌	medium	内容详细程度

搜索引擎类型

值	说明
search_std	智谱基础版搜索引擎
search_pro	智谱高阶版搜索引擎
search_pro_sogou	搜狗搜索
search_pro_quark	夸克搜索

时间范围过滤

值	说明
oneDay	一天内
oneWeek	一周内
oneMonth	一个月内
oneYear	一年内
noLimit	不限（默认）

内容详细程度

值	说明
medium	返回摘要信息，满足常规问答需求
high	最大化上下文，信息量大，适合需要细节的场景

6. 使用示例

基础搜索

请搜索"人工智能最新发展"

带时间过滤

请搜索最近一周关于"DevOps"的新闻

带域名过滤

请在 GitHub 上搜索 "OpenClaw" 相关内容

深度搜索

请搜索详细介绍"Kubernetes架构"的文章，需要详细内容

7. Docker部署

7.1 手动部署

# 构建镜像
docker build -t zhipu-mcp .

# 运行容器
docker run -d \
  --name zhipu-mcp \
  -p 8000:8000 \
  -e ZHIPU_API_KEY="your-api-key-here" \
  zhipu-mcp

7.2 Docker Compose

# 设置环境变量
export ZHIPU_API_KEY="your-api-key-here"

# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f

8. 调试

使用MCP Inspector

# 安装
npm install -g @anthropic-ai/mcp-inspector

# 运行
npx @anthropic-ai/mcp-inspector

# 在Inspector中连接
# URL: http://127.0.0.1:8000/mcp

9. 常见问题

Q: MCP连接失败？

A: 检查以下几点：

• MCP服务器是否已启动
• 端口是否正确（默认8000）
• 防火墙是否阻止连接
• API Key是否正确设置

Q: 搜索没有结果？

A: 检查：

• API Key是否有效
• 搜索查询是否合适（建议小于70字符）
• 网络连接是否正常

Q: 如何查看服务器日志？

A: 启动时添加日志参数：

uv run zhipu-websearch-mcp --log-level debug

10. 相关链接

• 智谱AI开放平台
• Web Search API文档
• MCP协议
• 项目GitHub