local-data-mcp

An MCP server that exposes a local SQLite database to LLM clients (Claude Desktop, Claude Code, MCP Inspector, …) as structured, read-only tools.

Every tool returns a Pydantic model, so clients get both an outputSchema up front and typed structuredContent in each result (plus a JSON text fallback for older clients).

Quick start

uv sync
uv run local-data-mcp --seed          # creates data/store.db with sample store data
uv run pytest                         # 16 tests, incl. a real stdio round-trip
uv run local-data-mcp                 # serve over stdio

Point it at your own database with --db path/to/file.db or LOCAL_DATA_DB=.... The generic tools (list_tables, describe_table, run_query) work on any SQLite file. The domain tools assume the sample schema, so replace them with ones that fit your data (see "Adapting" below).

Related MCP server: Read-Only SQLite Shop Database MCP Server

What it exposes

All tools carry readOnlyHint / idempotentHint annotations.

Safety model

• Connections open the file with mode=ro, so SQLite itself refuses writes.

• run_query also installs a SQLite authorizer that denies everything except SELECT/READ/FUNCTION/RECURSIVE. That covers cases like WITH x AS (...) DELETE ..., ATTACH and pragmas.

• Only one statement is allowed per call, and results are capped at limit (max 1000), with a truncated flag.

• Table names in describe_table are checked against sqlite_master and never interpolated from raw input.

• Bad input becomes a tool error (isError: true) that the model can read and recover from, not a crash.

Connect a client

Claude Code

claude mcp add local-data -- uv --directory /ABSOLUTE/PATH/local-data-mcp run local-data-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "local-data": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/local-data-mcp", "run", "local-data-mcp"],
      "env": { "LOCAL_DATA_DB": "/ABSOLUTE/PATH/local-data-mcp/data/store.db" }
    }
  }
}

MCP Inspector (interactive debugging)

npx @modelcontextprotocol/inspector uv run local-data-mcp

Over HTTP: uv run local-data-mcp --transport streamable-http serves at http://127.0.0.1:8000/mcp.

In stdio mode, stdout carries the protocol. Never print() to stdout in server code; log to stderr.

Layout

src/local_data_mcp/
  __init__.py   CLI entry point (--db, --seed, --transport)
  server.py     MCPServer: tools, resource, prompt
  models.py     Pydantic output models -> outputSchema / structuredContent
  db.py         read-only SQLite access + authorizer
  seed.py       deterministic sample database
tests/          in-memory client tests + stdio end-to-end test

Adapting to your own data

1. Swap Database in db.py for your source (CSV via csv/DuckDB, a JSON folder, Postgres, …).

2. Model each answer shape in models.py.

3. Add one @mcp.tool() per question the model should be able to answer. Give each a clear docstring (it becomes the tool description) and Annotated[..., Field(description=...)] parameters (they become the input schema).