Tavily搜索MCP服务器——克劳德桌面指南
使用本指南将Tavily Search MCP服务器连接到 克劳德桌面 在macOS上——本地（Docker或Python）或远程云VM上。
建筑
本地模式（stdio）
graph LR
subgraph Your Machine
Claude[Claude Desktop] |stdio| Server[mcp-search-agent]
end
Server |HTTPS| Tavily[Tavily API]云模式（流式HTTP）
graph LR
subgraph Your Machine
Claude[Claude Desktop]
end
subgraph Cloud VM ["Cloud VM (CLOUD_IP)"]
Server[mcp-search-agent :8080]
end
subgraph External
Tavily[Tavily API]
end
Claude |"Streamable HTTP · http://CLOUD_IP:8080/mcp"| Server
Server |HTTPS| Tavily请求流
sequenceDiagram
participant User
participant Claude as Claude Desktop
participant MCP as MCP Server
participant Tavily as Tavily API
User->>Claude: "Search for latest AI news"
Claude->>MCP: tavily_search(query="latest AI news")
MCP->>Tavily: POST https://api.tavily.com/search
Tavily-->>MCP: JSON results
MCP-->>Claude: Formatted text response
Claude-->>User: Summary of search results先决条件
- Tavilly API密钥 --免费获得一个 tavily.com
- 克劳德桌面 — 下载 并安装
设置选项
graph TD
Start[Choose Setup Method] --> Docker["Option 1: Local Docker"]
Start --> Local["Option 2: Local Python"]
Start --> Cloud["Option 3: Cloud VM"]
Docker --> D1[Build image]
D1 --> D2[Add to claude_desktop_config.json]
D2 --> D3[Restart Claude Desktop]
Local --> L1[Install Python 3.12+]
L1 --> L2[pip install dependencies]
L2 --> L3[Add to claude_desktop_config.json]
L3 --> L4[Restart Claude Desktop]
Cloud --> C1[Build image locally]
C1 --> C2[Deploy to VM]
C2 --> C3[Run in streamable-http mode]
C3 --> C4["Point Claude Desktop to http://CLOUD_IP:8080/mcp"]______________________________________________________________________
选项1：本地Docker（推荐）
用途 Dockerfile.local 和 mcp_search_server_local.py --一个最小的仅支持stdio的映像，没有暴露的端口。
1.构建本地Docker镜像
cd search_agent
docker build -f Dockerfile.local -t mcp-search-agent-local .或者使用Makefile：
make build-local2.配置克劳德桌面
打开Claude Desktop配置文件：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json添加以下内容（使用您自己的密钥替换API密钥）：
{
"mcpServers": {
"search-agent": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TAVILY_API_KEY=tvly-YOUR_API_KEY_HERE",
"mcp-search-agent-local"
]
}
}
}3.重新启动克劳德桌面
退出克劳德桌面(Cmd + Q)然后重新打开它。MCP服务器将出现在工具菜单中（锤子图标）。
______________________________________________________________________
选项2：本地Python
1.安装依赖项
需要 Python 3.12+.
cd search_agent
pip install -r requirements.txt这将安装：
mcp[cli]--MCP服务器框架tavily-python-Tavilly API客户
2.设置API密钥
导出shell中的密钥（或依赖脚本中的默认密钥）：
export TAVILY_API_KEY=tvly-YOUR_API_KEY_HERE3.配置克劳德桌面
打开配置文件：
code ~/Library/Application\ Support/Claude/claude_desktop_config.json添加以下内容（调整路径以匹配您的系统）：
{
"mcpServers": {
"search-agent": {
"command": "python3",
"args": [
"/Users/YOUR_USERNAME/../mcp_search_server_local.py"
],
"env": {
"TAVILY_API_KEY": "tvly-YOUR_API_KEY_HERE"
}
}
}
}注： 使用完整的绝对路径mcp_search_server_local.py.Claude Desktop无法扩展~或相对路径。
4.重新启动克劳德桌面
退出(Cmd + Q)并重新开放。服务器将可用。
______________________________________________________________________
选项3：云VM部署
将MCP服务器部署到远程VM，以便Claude Desktop通过Streamable HTTP通过网络连接。
部署流程
sequenceDiagram
participant Dev as Your Machine
participant VM as Cloud VM (CLOUD_IP)
participant Claude as Claude Desktop
participant Tavily as Tavily API
Dev->>Dev: docker build -t mcp-search-agent .
Dev->>VM: docker save | scp | docker load
VM->>VM: docker run --transport streamable-http -p 8080:8000
Note over VM: Server listening on :8080
Claude->>VM: HTTP connection to http://CLOUD_IP:8080/mcp
Claude->>VM: tavily_search(query="...")
VM->>Tavily: POST /search
Tavily-->>VM: JSON results
VM-->>Claude: Formatted response1.构建Docker镜像（本地）
重要提示： 映像必须与VM的体系结构匹配。如果你使用的是苹果Silicon（arm64），VM是x86（amd64），Makefile会自动处理这个问题 --platform linux/amd64.cd search_agent
make build2.部署到VM
选项A——使用Makefile（一个命令）：
make deploy CLOUD_IP=user@1.2.3.4 TAVILY_API_KEY=tvly-YOUR_KEY这将：
- 将Docker镜像保存到tarball
- 通过以下方式将其上传到VM
scp - 将其加载到VM上的Docker中
- 在端口8080上启动容器
选项B——手动步骤：
# Save and upload the image
docker save mcp-search-agent | gzip > /tmp/mcp-search-agent.tar.gz
scp /tmp/mcp-search-agent.tar.gz user@CLOUD_IP:/tmp/
# SSH into the VM and start the container
ssh user@CLOUD_IP
docker load **提示：** 使用完整路径 `npx` （奔跑 `which npx` 找到它）。Claude Desktop不继承您的shell `PATH`The `--allow-http` 标志是必需的，因为 `mcp-remote` 默认情况下阻止非HTTPS URL。
### 6.重新启动克劳德桌面
退出(`Cmd + Q`)并重新开放。
### 管理云服务器
Check status
ssh user@CLOUD_IP "docker ps | grep mcp-search-agent"
View logs
ssh user@CLOUD_IP "docker logs -f mcp-search-agent"
Stop the server
ssh user@CLOUD_IP "docker stop mcp-search-agent && docker rm mcp-search-agent"
Restart the server
ssh user@CLOUD_IP "docker restart mcp-search-agent"
### VM重新启动后
容器是通过以下方式创建的 `--restart unless-stopped`，所以Docker启动时它会自动启动。确保Docker本身在启动时启用：
Check if Docker starts on boot
ssh user@CLOUD_IP "sudo systemctl is-enabled docker"
Enable if needed
ssh user@CLOUD_IP "sudo systemctl enable docker"
如果容器已被移除，请重新创建它：
ssh user@CLOUD_IP "docker run -d --name mcp-search-agent --restart unless-stopped \ -p 8080:8000 \ -e TAVILY_API_KEY=tvly-YOUR_KEY \ mcp-search-agent --transport streamable-http"
Docker镜像在VM上保持不变——只有在本地重建时才需要重新上传。
______________________________________________________________________
## 验证连接
重新启动Claude Desktop后：
1. 打开新对话
1. 寻找 **锤图标** (🔨) 在输入区域中，它表示MCP工具可用
1. 点击锤子确认 `tavily_search` 被列入
1. 使用提示进行测试：Search for "latest developments in quantum computing"
克劳德会打电话给 `tavily_search` 工具并返回汇总结果。
## 工具参考
|工具|参数|说明|
|------|-----------|-------------|
| `tavily_search` | `query` （字符串，必填）|使用Tavily搜索网页|
| | `search_depth` （字符串，可选）| `"basic"` 或 `"advanced"` （默认值： `"advanced"`) |
## 故障排除
### 服务器未出现在Claude Desktop中
graph TD A[Server not showing?] --> B{Config file valid JSON?} B -->|No| C[Fix JSON syntax] B -->|Yes| D{Docker image built?} D -->|No| E["Run: docker build -t mcp-search-agent ."] D -->|Yes| F{Restarted Claude Desktop?} F -->|No| G[Cmd+Q and reopen] F -->|Yes| H[Check logs below]
### 检查克劳德桌面日志
View MCP-related logs
tail -f ~/Library/Logs/Claude/mcp*.log
### 常见问题
|问题|原因|修复|
|---------|-------|-----|
|工具未列出|配置未加载|重新启动Claude Desktop(`Cmd + Q`) |
|Docker错误|映像未构建|运行 `docker build -t mcp-search-agent .` |
|API错误| Tavily密钥无效|在验证密钥 [tavily.com](https://tavily.com/) |
|找不到Python |配置中的路径错误|使用完整的绝对路径 `python3` 和脚本|
|权限被拒绝|脚本不可执行|运行 `chmod +x mcp_search_server.py` |
|云：连接被拒绝|防火墙阻止端口|安全组中的开放端口8080/ `ufw` |
|云：连接超时| IP错误或服务器未运行|用验证 `curl http://CLOUD_IP:8080/mcp` |
|云：exec格式错误|为错误的架构构建的映像|使用重建 `--platform linux/amd64` （参见Makefile）|
|mcp-remote:非HTTPS错误| `mcp-remote` 阻止纯HTTP |添加 `"--allow-http"` 到args|
|mcp-remote:服务器已断开连接|云服务器未运行或代码陈旧|检查VM容器日志： `docker logs mcp-search-agent` |
### 手动测试服务器
**本地Docker（stdio）：**
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | docker run -i --rm -e TAVILY_API_KEY=tvly-YOUR_KEY mcp-search-agent-local
**本地Python（stdio）：**
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | python3 mcp_search_server_local.py
**云Docker（流式HTTP）：**
curl -s -X POST http://CLOUD_IP:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"protocolVersion":"2025-03-26","clientInfo":{"name":"test","version":"0.1"}}}'
对于stdio模式，您将看到具有服务器功能的JSON响应。对于HTTP，您应该得到一个JSON响应，其中包含 `serverInfo` 和 `capabilities`.
______________________________________________________________________
## 文件概述
|文件|目的|
|------|---------|
| `mcp_search_server_local.py` |本地MCP服务器——仅限stdio，最小|
| `mcp_search_server.py` |云MCP服务器--stdio+流式http传输|
| `Dockerfile.local` |本地Docker镜像--stdio，无暴露端口|
| `Dockerfile` |云Docker镜像——暴露端口8000（映射到主机上的8080）|
| `Makefile` | `build-local`, `run-local`, `build`, `deploy`等等。 |
| `tavily_client.py` |独立Tavily客户端（用于测试）|
| `requirements.txt` |Python依赖关系|
| `test_mcp_server.sh` |自动诊断脚本|
| `claude_readme.md` |本指南——克劳德桌面设置（本地+云）|