MCP-Excel

MCP-Excel — Google Sheets CRM MCP 服务

一个无状态的 MCP 服务，可将任意 Google Sheet 转换为包含 4 种实体（Lead、Organization、Contact、Activity）的 CRM。可作为独立 HTTP 服务运行（FastMCP streamable-HTTP，默认端口为 5002），也可通过 stdio 为 Claude Desktop 和其他本地 MCP 主机提供服务——无需网关、无需 ngrok，也无需启动子进程。

---

架构

Any MCP host (Claude Desktop, your backend, an agent framework)
  │  HTTP POST /mcp  (JSON-RPC) — or stdio
  ▼
MCP-Excel :5002  (FastMCP streamable-HTTP)
  │  gspread
  ▼
Google Sheets API

每次工具调用都必须显式包含 sheet_id——没有会话状态，也没有“活动工作表”变量。多个团队可以安全地使用同一个运行实例，因为请求之间不会共享任何内容。

---

工作表架构（自动管理）

包含 4 个标签页；首次连接时，如果标签页不存在，就会创建。现有标签页将按原样使用；缺少的列会追加，不会影响现有数据。

标签页	主键	关键列
Lead	Lead ID	Organization ID、Status、Segment、Opportunity Details、Last Contact Date
Organization	Organization ID	Organization Name、Industry Domain、Sub Domain、Company Type、Website
Contact	Contact ID	First Name、Last Name、Organization ID、Designation、Mobile、Email、LinkedIn Profile
Activity	Activity ID	Lead ID、Organization ID、Contact ID、Activity Type、Activity Sub-Type、Subject、Discussion Summary、Outcome

ID 会按照现有模式自动递增（LD001 → LD002、ACT010 → ACT011）。如果找不到一致的模式，则使用 UUID。

如果尚不存在，每个标签页还会追加 Created At、Updated At、Deleted 审计列。

系统会模糊匹配标题（解析同义词和近似重复项），因此列名略有不同的现有工作表也能正常使用。运行 tool_dedupe_headers（先进行试运行）即可合并确实重复的列。

---

设置

1. Google 服务账号

你需要一个启用了 Google Sheets API 和 Google Drive API 的服务账号密钥文件 creds.json。

将其放在此目录（默认路径），或将 GOOGLE_APPLICATION_CREDENTIALS 设置为该文件的完整路径。

切勿将 creds.json 提交到 git。 它已在 .gitignore 中排除；请将其保存在本地，或将其挂载为密钥。

2. 分享工作表

对于要连接的每个 Google Sheet：打开工作表 → 点击 Share → 添加服务账号邮箱并设为 Editor → 点击 Done。

服务账号邮箱会在启动时打印出来；发生权限错误时，也会由 get_sheet_info 返回。你也可以从 creds.json 中读取：

python3 -c "import json; print(json.load(open('creds.json'))['client_email'])"

3. 安装依赖项

pip install -r requirements.txt

可选 — 添加名片 OCR（Claude Vision）支持：

pip install anthropic
export ANTHROPIC_API_KEY=...

---

运行

本地开发（HTTP 端口 :5002）

GOOGLE_APPLICATION_CREDENTIALS=creds.json python mcp_excel_server.py

验证服务是否正常：

curl -s -X POST http://localhost:5002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | python3 -m json.tool

Docker（预发布 / 生产环境）

docker build -t mcp-excel .
docker run -p 5002:5002 \
  -v /path/to/creds.json:/secrets/creds.json \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/creds.json \
  mcp-excel

Claude Desktop（stdio 传输）

设置 MCP_TRANSPORT=stdio，即可使用 stdio 替代 HTTP：

{
  "mcpServers": {
    "crm": {
      "command": "python",
      "args": ["/path/to/mcp-excel/mcp_excel_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/mcp-excel/creds.json",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

---

环境变量

变量	默认值	说明
GOOGLE_APPLICATION_CREDENTIALS	creds.json	服务账号 JSON 文件的路径
MCP_TRANSPORT	http	http 用于服务模式，stdio 用于 Claude Desktop
MCP_PORT	5002	HTTP 监听端口
ANTHROPIC_API_KEY	—	仅用于 tool_extract_business_card

---

工具

所有工具均为无状态工具 — 每次调用都需要提供 sheet_id（完整的 Google Sheets URL 或纯电子表格 ID）。

工具	描述
tool_get_sheet_info	验证访问权限，确保存在全部 4 个标签页，并确认写入权限
tool_add_record	向 Lead / Organization / Contact / Activity 添加记录
tool_list_records	列出记录，支持按列筛选（分页）
tool_search_records	在所有列中搜索关键词
tool_update_record	按主键 ID 更新现有记录的字段
tool_delete_record	软删除记录（将 Deleted 设为 true）
tool_get_related_records	通过外键查找记录（例如某个 Lead 的所有 Activity）
tool_get_pipeline_analytics	Lead 管道分析：总数、状态细分、细分市场细分
tool_dedupe_headers	查找并合并重复列（先生成试运行报告）
tool_extract_business_card	通过 Claude Vision 从名片图片中提取联系人字段（需要 ANTHROPIC_API_KEY）

---

开发

pip install pytest
pytest test_mcp_excel.py test_crm_local.py -v

测试完全离线运行（Google 调用已模拟）；无需凭据。

---

故障排除

问题	解决方法
status: failure, message: ""	找不到工作表 — 将其共享给服务账号并授予编辑者权限
Permission denied on sheet	重新共享给服务账号，并授予编辑者权限（而非查看者权限）
Cannot connect to MCP-Excel service	MCP-Excel 未运行 — 在 :5002 启动它
sheet_id is required and was empty	始终传入 sheet_id — 不存在隐式活动工作表
找不到标签页 / 列不正确	get_sheet_info 会自动创建缺失的标签页并追加缺失的列

---

许可证

MIT — 参见 LICENSE。由 Nife 构建。