<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="assets/banner-light.svg"> <img alt="fastmcp-sqlite banner" src="assets/banner-dark.svg" width="100%" style="max-width: 860px; border-radius: 12px; margin-bottom: 16px;"> </picture>

fastmcp-sqlite

A High-Performance, Token-Optimized SQLite Model Context Protocol (MCP) Server Built for AI Coding Agents.
Zero Native Build Toolchain · Sub-15ms Cold Start · Prompt Cache Prefix Stability (>97%) · VDBE Opcode Watchdog · Fast Non-Blocking Schema Discovery

<p align="center"> <a href="#overview-and-design-principles">Design Principles</a> • <a href="#quickstart">Quickstart</a> • <a href="#-1-prompt-ai-agent-bootstrapper">🤖 Agent Prompt</a> • <a href="#multi-agent-client-configuration">Client Matrix</a> • <a href="#mcp-tools-reference">Tools Reference</a> • <a href="#performance-and-tokenomics">Benchmarks & Tokenomics</a> • <a href="#architecture">Architecture</a> • <a href="#when-should-you-not-use-fastmcp-sqlite">When NOT to Use</a> </p> <!-- mcp-name: io.github.kenb38291-tech/fastmcp-sqlite --> <!-- Tier 1: Distribution, Runtime & Test Stability -->

<!-- Tier 2: Ergonomics, Tokenomics & Performance -->

<!-- Tier 3: AI Ecosystem & Standards -->

</div>

---

Overview and Design Principles

Many SQLite Model Context Protocol (MCP) servers in the ecosystem rely on Node.js native addons (better-sqlite3) or unbounded serialization formats, introducing distinct operational challenges in autonomous AI agent environments:

1. Native Build Toolchain Overhead: Relying on node-gyp or platform-specific C++ build toolchains (such as MSVC on Windows) introduces installation friction in minimal container environments, restricted CI/CD runners, and locked-down developer workstations.
2. Context Token Inefficiency: Formatting query results as verbose JSON object arrays repeats schema keys for every record, consuming 2.2x to 3.7x more context tokens than compact tabular representations.
3. Prompt Cache Invalidation: Injecting dynamic execution timestamps or metrics into response headers alters the message prefix, preventing KV-cache reuse on Claude, GPT-4o, and Gemini architectures.
4. Unbounded Query Execution: Executing full SELECT COUNT(*) table scans on multi-gigabyte databases creates prolonged disk read locks, while unconstrained recursive Common Table Expressions (WITH RECURSIVE) or Cartesian joins can stall agent stdio subprocesses.

fastmcp-sqlite addresses these challenges through a lightweight, standard-library architecture:

• Zero Native Build Dependencies: Pure Python implementation using the standard library sqlite3 and the official mcp SDK, eliminating C/C++ compilation requirements.
• Non-Blocking Schema Probing: Inspects sqlite_stat1 and performs rightmost Table B-Tree leaf seeks (MAX(_rowid_)) in $O(\log N)$ time, avoiding sequential disk scans.
• VDBE Opcode Watchdog: Employs SQLite's sqlite3_progress_handler bytecode instruction counter to halt runaway recursive queries within milliseconds without freezing the agent process.
• Prefix-Stable Serialization: Relocates execution timing metrics strictly to response footers, preserving >97% byte invariance across schema inspections for prompt cache retention.
• Token-Budgeted Serialization: Provides compact GitHub-flavored Markdown tables, vertical record inspection for wide schemas, 400-character cell truncation, and a 24KB UTF-8 payload ceiling.

┌─── MODEL CONTEXT PROTOCOL: INTERACTION TRACE ─────────────────────────────────────────────┐
│                                                                                          │
│  🤖 AI AGENT (Claude / Cursor / Antigravity / Windsurf / Cline)                          │
│  └─▶ Tool Call: schema(db="production.db")                                               │
│                                                                                          │
│  ⚡ fastmcp-sqlite Engine (Non-Blocking B-Tree Leaf Probe: 0.82 ms)                       │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ # SQLite Schema Overview: production.db (400 MB, WAL Mode, 256MB MMAP)             │  │
│  │ | Table Name | Type  | Columns | Est. Rows   | Primary Key | Foreign Keys          |  │
│  │ | :--------- | :---- | :-----: | :---------- | :---------- | :-------------------- |  │
│  │ | `users`    | table |   12    | ~2,500,000  | id (INTEGER)| None                  |  │
│  │ | `events`   | table |    8    | ~2,070,000  | id (INTEGER)| `user_id` -> users.id |  │
│  │ *Discovery Latency: 0.82 ms (B-Tree Leaf Probe: MAX(_rowid_) | 12 Shadows Hidden)*   │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                          │
│  🤖 AI AGENT (Typo in SQL Query: `SELECT user_nam FROM users`)                           │
│  └─▶ Tool Call: query(sql="SELECT user_nam FROM users")                                  │
│                                                                                          │
│  💡 Schema Diagnostics (<1.2 ms via difflib)                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ SQLite OperationalError: no such column: user_nam                                  │  │
│  │ └─ Suggestion: Column 'user_nam' does not exist. Did you mean: `username`?          │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                          │
│  🤖 AI AGENT (Runaway Accidental Cartesian / Recursive CTE Query)                        │
│  └─▶ Tool Call: query(sql="WITH RECURSIVE loop(n) AS (SELECT 1 UNION ALL...)")           │
│                                                                                          │
│  🛑 VDBE Opcode Watchdog Interruption (3.6 ms)                                           │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ OperationalError: Query execution aborted by watchdog: exceeded 50,000,000 opcodes. │  │
│  │ └─ Execution halted gracefully · Zero process hang · Transaction rolled back       │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘

---

Quickstart

fastmcp-sqlite runs as a headless standard I/O (stdio) JSON-RPC Model Context Protocol server directly managed by your AI coding assistant (Claude Desktop, Cursor, Antigravity, Windsurf, Cline).

Run instantly with uvx (Recommended)

Execute with uvx without pre-installing dependencies:

# Start with a specific SQLite database (read-only by default)
uvx fastmcp-sqlite --db /path/to/database.db

# Enable write operations (INSERT, UPDATE, DELETE, CREATE, DROP)
uvx fastmcp-sqlite --db /path/to/database.db --allow-write

# Load SQLite extensions (e.g. sqlite-vec) with automatic post-init security lockdown
uvx fastmcp-sqlite --db /path/to/database.db --extension /path/to/vec0.so --allow-write

[!NOTE] When executed directly in a terminal, fastmcp-sqlite listens quietly on stdio for JSON-RPC messages from MCP clients. To interactively inspect and test tools in a visual browser UI, launch with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx fastmcp-sqlite --db /path/to/database.db

Or install via pip / pipx:

pip install fastmcp-sqlite
fastmcp-sqlite --db /path/to/database.db --allow-write

---

🤖 1-Prompt AI Agent Bootstrapper

If you are using Claude Code, Cursor, Google Antigravity, Windsurf, or Cline, copy and paste this single prompt into your chat window to let your agent configure and verify fastmcp-sqlite automatically:

Please inspect my workspace for any SQLite database files (*.db, *.sqlite, *.sqlite3). Once located, configure fastmcp-sqlite in our MCP configuration file (e.g. .cursor/mcp.json, claude_desktop_config.json, or mcp_config.json) using command 'uvx' and args ['fastmcp-sqlite', '--db', '<ABSOLUTE_OR_WORKSPACE_PATH>', '--allow-write']. Then call the 'schema' tool to verify connectivity and show me an overview of the tables.

---

Multi-Agent Client Configuration

Connect fastmcp-sqlite to your AI coding assistant using the configuration blocks below:

[!IMPORTANT] Windows Path Formatting: In JSON configuration files on Windows, use forward slashes (e.g., "C:/path/to/database.db") or escaped backslashes ("C:\\path\\to\\database.db").
Path Resolution: Providing an absolute path guarantees reliable database resolution across all client environments.

<details open> <summary><strong>Claude Desktop (<code>claude_desktop_config.json</code>)</strong></summary>

Configuration file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json (or via Claude Settings → Developer → Edit Config)
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["fastmcp-sqlite", "--db", "/absolute/path/to/database.db", "--allow-write"]
    }
  }
}

[!TIP] Windows Store / MSIX Virtualization Note: If Claude Desktop was installed via the Windows Store package, Windows may virtualize the configuration path to %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json. Opening the file via Claude Settings → Developer → Edit Config always opens the active configuration.

</details> <details> <summary><strong>Cursor IDE (<code>.cursor/mcp.json</code>)</strong></summary>

Add to your project root .cursor/mcp.json or configure under Cursor Settings → Features → MCP:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["fastmcp-sqlite", "--db", "/absolute/path/t