智谱AI MCP 使用完全指南：从入门到实战
智谱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开放平台](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 获取 API Key
2.2 设置环境变量
export ZHIPUAPIKEY="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/claudedesktopconfig.json
Windows配置文件位置：
%APPDATA%\Claude\claudedesktopconfig.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字符） |
| searchengine | string | ❌ | searchstd | 搜索引擎类型 |
| search_intent | boolean | ❌ | false | 是否进行搜索意图识别 |
| count | integer | ❌ | 10 | 返回结果条数（1-50） |
| searchdomainfilter | string | ❌ | - | 白名单域名过滤 |
| searchrecencyfilter | string | ❌ | noLimit | 时间范围过滤 |
| content_size | string | ❌ | medium | 内容详细程度 |
搜索引擎类型
| 值 | 说明 |
|----|------|
| search_std | 智谱基础版搜索引擎 |
| search_pro | 智谱高阶版搜索引擎 |
| searchprosogou | 搜狗搜索 |
| searchproquark | 夸克搜索 |
时间范围过滤
| 值 | 说明 |
|----|------|
| 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 ZHIPUAPIKEY="your-api-key-here" \
zhipu-mcp
7.2 Docker Compose
# 设置环境变量
export ZHIPUAPIKEY="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开放平台](https://open.bigmodel.cn/)
- [Web Search API文档](https://docs.bigmodel.cn/api-reference/工具-api/网络搜索)
- [MCP协议](https://modelcontextprotocol.io/)
- [项目GitHub](https://github.com/xiispace/zhipu-mcp)
