使用说明

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-local

2.配置克劳德桌面

打开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_HERE

3.配置克劳德桌面

打开配置文件：

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 response

1.构建Docker镜像（本地）

重要提示： 映像必须与VM的体系结构匹配。如果你使用的是苹果Silicon（arm64），VM是x86（amd64），Makefile会自动处理这个问题 --platform linux/amd64.

cd search_agent
make build

2.部署到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 < /tmp/mcp-search-agent.tar.gz
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

3.打开防火墙端口

确保端口 8080 已在云VM的防火墙/安全组中打开：

云提供商	命令/设置
亚马逊云服务	安全组→ 入站→ TCP 8080
谷歌云平台	`gcloud compute firewall-rules create allow-mcp --allow tcp:8080`
Azure	NSG→ 入站→ TCP 8080
通用的	`sudo ufw allow 8080/tcp`

4.验证服务器是否正在运行

从本地计算机发送MCP初始化请求：

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"}}}'

您应该看到一个JSON响应 serverInfo 和 capabilities如果你得到 exec format error 在容器日志中，使用正确的平台重建映像（参见步骤1）。

5.配置克劳德桌面

打开配置文件：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

选项A——直接URL（克劳德桌面2025.3+）：

{
  "mcpServers": {
    "search-agent": {
      "url": "http://CLOUD_IP:8080/mcp"
    }
  }
}

选项B——使用 mcp-remote 桥（所有版本）：

如果您的Claude Desktop版本不支持 "url" 字段，使用 mcp-remote 桥接stdio↔ 流式HTTP。需要Node.js/ npx.

{
  "mcpServers": {
    "search-agent": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://CLOUD_IP:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

提示： 使用完整路径 npx （奔跑 which npx 找到它）。Claude Desktop不继承您的shell PATHThe --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后：

打开新对话
寻找 锤图标 (🔨) 在输入区域中，它表示MCP工具可用
点击锤子确认 tavily_search 被列入

使用提示进行测试：

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
找不到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`	本指南——克劳德桌面设置（本地+云）