MCP-Excel — Google Sheets CRM MCP Server

A stateless MCP server that turns any Google Sheet into a 4-entity CRM (Lead, Organization, Contact, Activity). Runs as a standalone HTTP service (FastMCP streamable-HTTP, default port 5002) or over stdio for Claude Desktop and other local MCP hosts — no gateway, no ngrok, no subprocess spawning required.

Architecture

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

Every tool call includes an explicit sheet_id — there is no session state, no "active sheet" variable. Multiple teams can use the same running instance safely because nothing is shared between requests.

Related MCP server: google-sheets-mcp

Sheet schema (auto-managed)

Four tabs, created on first connection if they don't exist. Existing tabs are used as-is; missing columns are appended without disturbing existing data.

IDs auto-increment continuing the existing pattern (LD001 → LD002, ACT010 → ACT011). Falls back to UUID if no consistent pattern is found.

Each tab also gets Created At, Updated At, Deleted audit columns appended if they aren't already present.

Headers are matched fuzzily (synonyms and near-duplicates are resolved), so an existing sheet with slightly different column names still works. Run tool_dedupe_headers (dry-run first) to merge genuine duplicate columns.

Setup

1. Google service account

You need a creds.json service account key with Google Sheets API and Google Drive API enabled.

Place it in this directory (the default path) or set GOOGLE_APPLICATION_CREDENTIALS to its full path.

Never commit creds.json to git. It is excluded in .gitignore; keep it local or mount it as a secret.

2. Share the sheet

For each Google Sheet you want to connect: open the sheet → Share → add the service account email as Editor → Done.

The service account email is printed at startup and returned by get_sheet_info on permission errors. It is also readable from creds.json:

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

3. Install dependencies

pip install -r requirements.txt

Optional — business-card OCR (Claude Vision) support:

pip install anthropic
export ANTHROPIC_API_KEY=...

Running

Local dev (HTTP on :5002)

GOOGLE_APPLICATION_CREDENTIALS=creds.json python mcp_excel_server.py

Verify it's healthy:

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 (staging / production)

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 transport)

Set MCP_TRANSPORT=stdio to use stdio instead of 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"
      }
    }
  }
}

Environment variables

Tools

All tools are stateless — every call requires sheet_id (full Google Sheets URL or bare spreadsheet ID).

Development

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

Tests run fully offline (Google calls are mocked); no credentials needed.

Troubleshooting

License

MIT — see LICENSE. Built by Nife.