网页搜索与表格处理服务器

MCP服务器演示：网页搜索 + Google表格

这是一个 模型上下文协议（MCP）服务器 用Python编写的，提供了两个工具：

• web_search 使用（某工具/方法）在网页上搜索 Tavily（可译为“塔维利”，但具体翻译可能需根据上下文或品牌命名习惯调整，此处为直译） API
• append_to_sheet 使用服务帐户将行追加到Google表格中

这是一个虽小但完整的示例 代理型人工智能工作流:
查找信息 → 根据信息采取行动。

特点/功能

• 使用官方工具构建 FastMCP Python SDK（软件开发工具包）。
• web_search 使用Tavily的API（免费套餐包含每月1,000+次查询）。
• append_to_sheet 使用OAuth服务帐户凭据调用Google Sheets REST API。
• 使用……进行测试 MCP 检查器 用于工具发现和调试。
• 代理/VPN安全： requests + 用于Sheets的服务账户令牌， httpx 为Tavily（注：Tavily可能是一个公司或项目名，根据上下文具体翻译，此处保留原样以作示例）。
• 极简、单文件服务器（server.py) 你可以通过添加更多工具来扩展它。

要求

• Ubuntu 24.04（或任何Linux/macOS系统；Windows WSL也适用）
• Python 3.10及以上版本
• Node.js 22+（通过 nvm（不重要了/没关系/算了）) 用于运行 Inspector（检查器）
• A. Tavily（注：此词可能为特定品牌或项目名，无直接对应中文翻译，故保留原样） API密钥
• 一个包含（特定内容/功能）的Google Cloud项目 电子表格API已启用 以及一个 服务账户 JSON 密钥
• 与您的服务账户电子邮件共享的目标Google表格（编辑权限）

设置

1. 克隆和虚拟环境（venv）

git clone https://github.com/<yourname>/mcp-websearch-sheets.git
cd mcp-websearch-sheets
python3 -m venv .venv
source .venv/bin/activate

2. 安装依赖项

pip install --upgrade pip
pip install "mcp[cli]" httpx requests google-api-python-client google-auth google-auth-httplib2

3. 导出环境变量

export TAVILY_API_KEY="tvly_xxx"
export GOOGLE_APPLICATION_CREDENTIALS="/abs/path/to/service_account.json"

# optional: proxy
# export http_proxy="http://user:pass@proxy:port"
# export https_proxy="http://user:pass@proxy:port"
# export NO_PROXY="localhost,127.0.0.1"

4. 运行服务器

source .venv/bin/activate
python server.py

这会在（指定位置/系统上）启动一个MCP服务器 **STDIO（标准输入输出）**它不会直接打印结果（所有日志都会发送到 stderr）。

🧪 使用MCP Inspector进行测试

1. 启动 Inspector（需要 Node 22+ 版本）：

   复制

   npx @modelcontextprotocol/inspector
   

   → 打开日志中显示的URL（http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...）。

2. 添加您的服务器：

   • 交通： STDIO 翻译为中文是“标准输入输出（Standard Input/Output）”。
   • 命令： /abs/path/to/.venv/bin/python
   • 参数： /abs/path/to/server.py
   • Env:（可能指“Environment”的缩写，即“环境”） TAVILY_API_KEY， GOOGLE_APPLICATION_CREDENTIALS

3. 调用工具：

   • 网络搜索
     复制

     {
       "query": "world population",
       "search_depth": "basic",
       "max_results": 3
     }
     

   • 在工作表中追加
     复制

     {
       "spreadsheet_id": "<YOUR_SHEET_ID>",
       "range_name": "Sheet1!A2:C",
       "rows": [["Ping","https://example.com","hello"]]
     }
     

   查看你的Google表格，里面有新增的一行！

代码概述

web_search

• 发送 POST 请求至 https://api.tavily.com/search
• 头球 Authorization: Bearer <TAVILY_API_KEY>
• 返回简化结果：标题、网址、摘要。

append_to_sheet

• 从（指定位置）读取服务账户的JSON文件 GOOGLE_APPLICATION_CREDENTIALS
• 用途 google-auth 生成一个短期有效的持有者令牌（Bearer token）
• 通话：
  复制

  POST https://sheets.googleapis.com/v4/spreadsheets/{id}/values/{range}:append
  ?valueInputOption=RAW&insertDataOption=INSERT_ROWS
  

• 在请求体中发送行数据；返回更新的行数。

为什么选择这个设计？

• MCP的（注：MCP在此处可能是一个缩写或特定术语，根据上下文可能代表不同的含义，如“最小成本路径”、“多通道处理器”等，但直接翻译时保持原样以保留其特定含义） @tool 装饰器使这两个函数对 Inspector（以及任何 MCP 客户端，包括 ChatGPT）可见。
• STDIO传输方式意味着它作为一个子进程运行，既干净又便携。
• httpx 和 requests 相互尊重 http_proxy/https_proxy。
• 我们避免了 httplib2 通过直接使用REST API与Sheets交互来实现特殊功能。

示例工作流程

1. 跑 web_search("AI chip shortage")。
2. 复制前3个结果。
3. 跑步 append_to_sheet(spreadsheet_id="...", range_name="Sheet1!A2:C", rows=results)。
4. 看到您的 Google 表格中实时填充搜索结果。

这展示了一个小型的代理循环： 搜索 → 持久化结果.

故障排除

• 表格处理超时检查代理/VPN。禁用VPN或添加到白名单 *.googleapis.com。
• “403 on Sheets”可以翻译为“在表格上显示403”或“表格中的403错误/状态”，具体翻译取决于上下文，但这里提供了一个较为通用的翻译确保目标工作表已与您的服务帐户电子邮件共享。
• **ModuleNotFoundError（模块未找到错误）**确保在虚拟环境中执行了 pip 安装。
• 检查器无法启动检查节点22+（nvm install 22）。

下一步

• 添加更多工具（例如，总结搜索结果、导出CSV文件）。
• 使用小型编排脚本自动连接工具。
• 作为Upwork/作品集的GitHub演示进行部署。

许可证

麻省理工学院（MIT）——自由使用、学习、扩展。

致谢

• 模型上下文协议
• Tavily搜索API
• Google Sheets API