jagabukit-mcp

A read-only MCP server over the JagaBukit reception Google Sheet — the same append-only sheet the WhatsApp receptionist in ../jagabukit-backend writes to. It lets any MCP client (Claude Desktop, Cursor, or a local Ollama-backed agent) query the reception data through five tools.

Built as a Forward-Deployed-Engineer proof: when a client's system has no connector, you write the MCP server that gives an agent access to it. Here the "client system" is the reception sheet; the server exposes it without touching the production write path.

Why this shape

• Read-only. The bot owns the append-only writes; this server never mutates the sheet. It mirrors store.ts's exact column order (store.py), so the two never drift.

• Runs with zero credentials. The default source reads local CSV fixtures, so you can demo, test, and develop with no Google auth and no API spend (same credit-safe discipline as the backend's fakes). Flip one env var to read the live sheet.

• Layered for testing. Pure parsing (store.py) → queries (queries.py) → thin MCP tools (server.py). The tools are wrappers, so tests and the smoke script exercise the real logic without a running client.

Related MCP server: @node2flow/google-sheets-mcp

Tools

Quick start

cd jagabukit-mcp
python -m venv .venv
.venv\Scripts\activate            # Windows  (source .venv/bin/activate on macOS/Linux)
pip install -r requirements.txt

# 1) Prove the data layer works — no model, no credentials:
python smoke.py

# 2) Run the tests:
pytest -q

# 3) Run the MCP server (stdio):
python server.py

Point it at the live sheet

cp .env.example .env
# set in .env:
#   JAGABUKIT_SHEET_SOURCE=google
#   JAGABUKIT_SPREADSHEET_ID=<the reception sheet id>
#   GOOGLE_APPLICATION_CREDENTIALS=./service-account.json   (read access to that sheet)
pip install google-api-python-client google-auth

The service account needs only the read-only Sheets scope. Share the sheet with the service account's email (Viewer) — no OAuth dance, it runs headless.

Connect it to a client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "jagabukit-reception": {
      "command": "python",
      "args": ["C:/Users/Riska/Documents/Utamation/jagabukit-mcp/server.py"]
    }
  }
}

Local / Ollama agent — this server speaks standard MCP over stdio, so any MCP-capable client works. For a fully-local, no-API-cost loop, drive it from an Ollama-backed MCP client (see the mcp_ai_agents examples in ../awesome-llm-apps). The server is model-agnostic — whatever model the client runs, these five tools look the same.

Layout

store.py       # pure row->dataclass parsing, mirrors jagabukit-backend store.ts
queries.py     # business logic over a SheetSource (recent, history, bookings, search, stats)
sources.py     # CsvSheetSource (default, offline) + GoogleSheetSource (live) + env picker
server.py      # FastMCP server: 5 read-only tools wrapping queries
smoke.py       # credit-safe: call every query directly and print results
fixtures/      # sample Conversation/Leads/Bookings/Reminders CSVs (fake Uluwatu data)
tests/         # pytest unit tests (deterministic, AAA)