🚀 Operation LOCAL-MCP

A fully local Postgres-backed MCP (Model Context Protocol) server, connected two ways: first to Claude Desktop (which speaks MCP natively), then to a fully local Ollama model via a hand-built bridge — since Ollama has no native MCP client. Both paths sit behind a FastAPI + Streamlit chat console.

Built as a diagnostic exercise as much as a build exercise: the core question was "where exactly does local-model tool-calling reliability break down?", and this project isolates that question with a small, controlled two-tool schema.

What it does

Ask questions in plain English about a local inventory/orders database:

• "What's in the inventory?"

• "What's John's total order amount?"

• "How many Widget B do we have?"

The model decides which tool to call, the tool runs a safe parameterized query against Postgres, and the result gets turned back into a natural-language answer.

Architecture

┌─────────────┐     stdio (MCP)     ┌──────────────────┐
│Claude Desktop│◄───────────────────►│                  │
└─────────────┘                     │  server.py       │──► Postgres
                                     │  (FastMCP)        │    (Docker)
┌─────────────┐   hand-built bridge  │                  │
│  Ollama      │◄───────────────────►│                  │
│ (qwen2.5:7b) │      (bridge.py)    └──────────────────┘
└──────┬───────┘
       │
       ▼
┌─────────────┐   HTTP   ┌─────────────┐
│  FastAPI     │◄────────►│  Streamlit   │
│  (main.py)   │          │  (app.py)    │
└─────────────┘          └─────────────┘

server.py is the single source of truth for the tools — both Claude Desktop and the Ollama bridge talk to the exact same FastMCP server. This was deliberate: it turns "does Claude Desktop succeed where Ollama fails?" into a clean A/B test, since the only variable that changes is the model, not the tool definitions.

Key finding

The starting hypothesis (from prior local-LLM tooling work) was that 7B–12B models are broadly unreliable at emitting well-formed tool calls. That held for dense, high-overhead schemas (e.g. Claude Code's tool surface), but did not hold here: qwen2.5:7b, given this project's small two-tool schema, correctly selected the right tool on every test — including inferring a sensible default parameter (min_quantity: 1) that wasn't stated in the prompt — and never once emitted malformed tool-call JSON.

Takeaway: the earlier reliability problem looks like it's driven more by schema size / context overhead than by a hard local-model capability ceiling. Worth revisiting the claude-code-router / hosted-API tradeoff with that in mind — schema simplification may solve more of the problem than switching providers does.

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

docker compose up -d              # Postgres, seeded via init.sql
ollama pull qwen2.5:7b            # or llama3.1:8b — confirm `tools` under
ollama show qwen2.5:7b            # Capabilities before relying on it

Running it

Path 1 — Claude Desktop (MCP native): Add an entry to claude_desktop_config.json pointing at src/server.py using your venv's Python (see repo history / commit log for the exact config that worked after a couple of path-resolution false starts — see Gotchas below).

Path 2 — Local Ollama console:

# terminal 1
uvicorn src.main:app --reload

# terminal 2
streamlit run src/app.py

Then open the Streamlit URL and ask questions in the chat box.

Gotchas hit along the way (kept for the next person, including future me)

• python -m src.server works from a terminal but not from Claude Desktop's launched subprocess — its cwd handling doesn't reliably put the project root on Python's module search path for -m resolution. Fix: point claude_desktop_config.json directly at the script file (args: ["/abs/path/src/server.py"]) instead of using -m.

• tool.inputSchema vs tool.input_schema — the wire-protocol field name and the installed mcp SDK's Python attribute name don't match; the SDK uses snake_case. Worth checking installed SDK attribute names directly rather than assuming they mirror the protocol spec.

• init.sql only runs against Postgres on a fresh Docker volume. If you've already got a pgdata volume from a prior run, editing init.sql and re-running docker compose up silently does nothing — you need docker compose down -v first to force re-seeding.

• Model function-call arguments arrive as either a dict or a JSON string depending on the model/quantization — bridge.py's loop handles both.

Known limitations

• No multi-turn memory. Each /chat request (and each run_tool_call_loop call) starts a fresh conversation with no history from prior turns. The Streamlit UI displays prior turns for readability, but doesn't send them back to the backend — a deliberate scope cut for this iteration, not an oversight.

• Each request respawns the MCP server subprocess rather than keeping one long-lived session — simpler and correct for this scale, but adds latency you'd want to remove for anything beyond a local demo.

• Read-only by design: both tools run fixed, parameterized SELECTs. No write/update tools exist, intentionally, to keep the safety surface small.

Stack

Python 3.12 · FastMCP · MCP SDK · Ollama (qwen2.5:7b) · PostgreSQL (Docker) · FastAPI · Streamlit · psycopg2

Repo layout

local-mcp-postgres/
├── README.md
├── MISSION_PLAN.md        # phase-by-phase build log / checklist
├── docker-compose.yml
├── init.sql
├── requirements.txt
└── src/
    ├── server.py           # FastMCP server: fetch_inventory, fetch_order_total
    ├── bridge.py            # Ollama-MCP bridge + tool-call loop
    ├── main.py               # FastAPI backend
    └── app.py                 # Streamlit console