sqlite-mcp-server
Connects LLM assistants to local SQLite databases, enabling schema discovery, table inspection, read-only SELECT and EXPLAIN queries, and direct access to database schema and table context through MCP resources and prompts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sqlite-mcp-server list all tables and describe the users table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
๐ 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) withPRAGMA query_only = ON;.
Context Overflow Protection (
max_rows): Safely truncates large query results with an informative warning advising AI models to useLIMITandOFFSETclauses.Structured Error Handling for AI: Returns standardized JSON error envelopes (
error_type,message,query, andsuggestion) 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 |
| Lists all tables and views in the database with estimated row counts. |
|
| Retrieves column definitions, data types, nullability, default values, primary keys, foreign keys, and indexes for a specific table. |
|
| Returns the complete DDL schema definition for all tables, views, and indexes. |
|
| Safely executes a read-only |
|
๐ฆ 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, safeSELECTquery 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 runlist_tables).ColumnNotFoundError: Column was not found (includes advice to rundescribe_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 ormax_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.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.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
Open Cursor Settings (
Ctrl + Shift + Jon Windows/Linux orCmd + ,on macOS).Navigate to Features > MCP Servers.
Click + Add New MCP Server.
Fill in:
Name:
sqlite-mcp-serverType:
commandCommand:
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 toolsdescribe_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Query 40 databases from Claude, ChatGPT, or Cursor โ on any device. Read-only, encrypted, audited.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query your Postgres from ChatGPT or Claude without exposing the database or handing over credentials. Run npx boltschema connect next to your database and it dials out over HTTPS โ no inbound firewall rule, no open port, works with localhost and VPC-private databases. Read-only is enforced by a SQL guard, a Postgres READ ONLY transaction, and a scoped role generated for you.
Query PostgreSQL databases in plain English โ LLM-generated, safety-validated SQL.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables safe, read-only SQL access to SQLite databases for AI agents, allowing schema exploration and SELECT queries with defense-in-depth protections.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to explore and query SQLite databases through read-only tools, with defense-in-depth sandboxing preventing any data modifications.MIT
- FlicenseAqualityDmaintenanceEnables 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-
- AlicenseBqualityCmaintenanceEnables 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.2MIT