Skip to main content
Glama
sqlite-mcp-server

sqlite-mcp-server

sqlite-mcp-server

An open-source Model Context Protocol (MCP) server connecting LLM assistants (such as Claude Desktop and Cursor) to local SQLite databases with strict read-only security, context overflow protection, and structured AI error handling.

CI M8ven Score Glama Score License: MIT Python 3.10+


๐ŸŒŸ Key Features

  • Automated Schema Discovery: Automatically inspect table lists, object types (tables/views), row count estimates, columns, primary keys, foreign keys, and complete DDL definitions.

  • Strict Read-Only Query Security:

    • Parser-Level Validation: Rejects all mutation statements (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, VACUUM, REINDEX, etc.).

    • Statement Chaining Prevention: Blocks execution of multiple chained statements separated by ;.

    • Restricted PRAGMAs: Prohibits dangerous PRAGMAs (writable_schema, permissions, and configuration mutation).

    • Engine-Level Enforcement: SQLite connections are opened using read-only URI mode (file:path?mode=ro) with PRAGMA query_only = ON;.

  • Context Overflow Protection (max_rows): Safely truncates large query results with an informative warning advising AI models to use LIMIT and OFFSET clauses.

  • Structured Error Handling for AI: Returns standardized JSON error envelopes (error_type, message, query, and suggestion) to allow AI models to self-correct queries without hallucinations.

  • Full MCP Capabilities: Exposes Tools, direct Resources (sqlite://schema, sqlite://tables), and guided Prompts (schema_analysis, safe_query_assistant).

  • Flexible Configuration: Set the database path via CLI argument (--db-path), environment variable (SQLITE_DB_PATH), or dynamically per tool invocation (db_path).


Related MCP server: sqlite-analyst

๐Ÿ› ๏ธ MCP Tools

Tool Name

Description

Key Arguments

list_tables

Lists all tables and views in the database with estimated row counts.

db_path (optional)

describe_table

Retrieves column definitions, data types, nullability, default values, primary keys, foreign keys, and indexes for a specific table.

table_name (required), db_path (optional)

get_database_schema

Returns the complete DDL schema definition for all tables, views, and indexes.

db_path (optional)

read_query

Safely executes a read-only SELECT or EXPLAIN query and returns structured row records.

query (required), params (optional), max_rows (optional, default: 1000), db_path (optional)


๐Ÿ“ฆ MCP Resources & Prompts

MCP Resources (Direct Context Access)

Clients that support MCP Resources can inspect the database context directly without invoking a tool:

  • sqlite://schema: Returns the full formatted SQL DDL schema of the database.

  • sqlite://tables: Returns a concise list of all tables, views, and their respective row counts.

MCP Prompts (Interactive Assistant Guides)

  • schema_analysis: Prompts the AI model to inspect database structure, relationships, normalization, and optimization opportunities.

  • safe_query_assistant(user_goal): Guides the AI model in formulating an optimized, safe SELECT query tailored to the user's objective.


๐Ÿ“‹ Structured Error Format

When a syntax or validation error occurs, the server responds with a structured JSON object designed for LLM consumption:

{
  "success": false,
  "error_type": "DisallowedQueryError",
  "message": "Forbidden modification keyword 'DROP' detected. Only read operations are allowed.",
  "query": "DROP TABLE employees;",
  "suggestion": "Remove any data modification or schema alteration commands. Only SELECT queries are permitted."
}

Supported error categories:

  • DisallowedQueryError: Query attempts data modification or invokes forbidden SQL operations.

  • SyntaxError: SQLite syntax error.

  • TableNotFoundError: Table was not found (includes advice to run list_tables).

  • ColumnNotFoundError: Column was not found (includes advice to run describe_table).

  • DatabaseNotFoundError: Database file does not exist at the specified path.

  • DatabaseConfigError: No database path was provided or configured.

  • ValidationError: Invalid input parameter (e.g. empty table name or max_rows < 1).


๐Ÿš€ Installation & Getting Started

Option 1: Run with uvx (Recommended)

If you have uv installed, run the server instantly without cloning:

uvx sqlite-mcp-server --db-path "/path/to/database.db"

Option 2: Install from Source

# 1. Clone repository
git clone https://github.com/Aderali06/sqlite-mcp-server.git
cd sqlite-mcp-server

# 2. Create virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# 3. Install package and development dependencies
pip install -e ".[dev]"

โš™๏ธ Claude Desktop Configuration

Add the server to your claude_desktop_config.json:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Example:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "sqlite-mcp-server",
        "--db-path",
        "C:/Users/A2/Documents/database.db"
      ]
    }
  }
}

Or using local Python:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": [
        "-m",
        "src.server",
        "--db-path",
        "C:/Users/A2/Documents/database.db"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

๐Ÿ’ป Cursor Integration

Method 1: Via Cursor Settings UI

  1. Open Cursor Settings (Ctrl + Shift + J on Windows/Linux or Cmd + , on macOS).

  2. Navigate to Features > MCP Servers.

  3. Click + Add New MCP Server.

  4. Fill in:

    • Name: sqlite-mcp-server

    • Type: command

    • Command: python -m src.server --db-path "C:/path/to/database.sqlite"

Method 2: Project-Level Configuration (.cursor/mcp.json)

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "sqlite": {
      "command": "python",
      "args": [
        "-m",
        "src.server",
        "--db-path",
        "${workspaceFolder}/data/app.db"
      ]
    }
  }
}

๐Ÿงช Testing

Run the automated test suite with pytest:

# Run all tests
pytest

# Run tests with test coverage reporting
pytest --cov=src --cov-report=term-missing

๐Ÿ“‚ Project Structure

sqlite-mcp-server/
โ”œโ”€โ”€ .github/
โ”‚   โ””โ”€โ”€ workflows/
โ”‚       โ”œโ”€โ”€ ci.yml              # Multi-OS CI testing (Linux & Windows)
โ”‚       โ””โ”€โ”€ publish.yml         # Automated PyPI release workflow
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ __init__.py             # Package version & metadata
โ”‚   โ””โ”€โ”€ server.py               # FastMCP server, tools, resources, prompts & SQL validation
โ”œโ”€โ”€ tests/
โ”‚   โ””โ”€โ”€ test_server.py          # 29 unit & integration pytest tests
โ”œโ”€โ”€ .gitignore                  # Git ignore rules
โ”œโ”€โ”€ LICENSE                     # Official MIT License
โ”œโ”€โ”€ pyproject.toml              # Build system, CLI entrypoint, & package metadata
โ”œโ”€โ”€ README.md                   # Project documentation & configuration guide
โ””โ”€โ”€ requirements.txt            # Python dependencies

๐Ÿ“„ License

This project is licensed under the MIT License.

Available Tools

4 tools
describe_tableA

Get detailed schema information for a specific table or view, including columns, primary keys, foreign keys, and indexes.

Args: table_name: The name of the table or view to inspect. db_path: Optional path to SQLite file. If omitted, uses default database path.

Inputs: table_name (required), db_path. Returns: object

get_database_schemaA

Get the full CREATE DDL statements and schema definitions for all tables, views, and indexes.

Args: db_path: Optional path to SQLite file. If omitted, uses default database path.

Inputs: db_path. Returns: object

list_tablesB

List all user tables and views in the SQLite database with their row count.

Args: db_path: Optional path to SQLite file. If omitted, uses default database path.

Inputs: db_path. Returns: object

read_queryA

Execute a safe, read-only SELECT query against the SQLite database.

Args: query: The SQL SELECT query to execute. Mutation queries (INSERT, UPDATE, DELETE, DROP, etc.) are strictly rejected. params: Optional list of query parameters for prepared statements (? placeholders). max_rows: Maximum number of rows to return (default: 1000). Protects against context overflow. db_path: Optional path to SQLite file. If omitted, uses default database path.

Inputs: query (required), params, db_path, max_rows. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation4/5

    list_tables, describe_table, and get_database_schema have some overlap in scope (schema/table inspection), but each operates at a clearly different granularity: table list with counts, single-table detail, and full DDL. read_query is cleanly distinct as the data-retrieval tool. An agent can reasonably pick the right one.

    Naming Consistency4/5

    Names are snake_case verb_noun throughout (list_tables, describe_table, get_database_schema, read_query), which is readable and predictable. Minor deviation in that three verbs (list/describe/get) are used for closely related inspection tasks rather than one consistent verb.

    Tool Count5/5

    Four tools is well-scoped for a read-only SQLite inspection server, with each tool earning its place and no redundancy. Nothing feels padded or thin for the stated purpose.

    Completeness4/5

    The read-only inspection surface (list tables, describe table, full DDL, run SELECT) covers the core discovery and query workflow with no dead ends. Gaps exist around write/mutation operations and query-plan/explain introspection, but those are plausibly out of scope for a deliberately read-only server.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to explore and query SQLite databases through read-only tools, with defense-in-depth sandboxing preventing any data modifications.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query SQLite databases using plain language, with strict read-only enforcement and column-level access control to prevent damage or unauthorized data reads.
      4
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to safely run read-only SQL against SQLite databases through whitelist-validated queries, capped result sets, and confined file paths. It also exposes schema inspection so models can discover tables and columns before querying.
      2
      MIT