Which integrations are available for this server?

Provides safe, read-only access to a SQLite database, allowing AI agents to list tables, describe schemas, and execute read-only SQL queries with pagination.

How do I use MCP SQLite Server (Read-Only)?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP SQLite Server (Read-Only) List the tables in the database" 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.

de en es ja ko ru zh

MCP SQLite Server (Read-Only)

by ilyassakhanov

Overview Schema Source Related Servers Discussions Admin

Python

Local

MCP SQLite Server (Read-Only)

A production-ready Model Context Protocol server that provides AI agents with safe, read-only access to a SQLite database (shop.db). Built with the official mcp Python SDK using the stdio transport.

Features

3 MCP tools: list_tables, describe_table, query_database
Defense-in-depth read-only safety: SQLite URI read-only mode + PRAGMA query_only + SQL validator + EXPLAIN opcode inspection
Query validation: Rejects INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/REPLACE/TRUNCATE/ATTACH/DETACH, multi-statement queries (;), SQL comments (--, /* */), and modifying PRAGMA — without false positives on string literals
Pagination: Default row limit (100), limit/offset parameters, truncated-output flag
Stderr-only logging: All logs/tracebacks go to sys.stderr; stdout is reserved exclusively for JSON-RPC
Full type hints: mypy --strict clean
TDD: 105 tests covering security, DB layer, MCP tools, 8 benchmark queries, and the stderr guard

Related MCP server: shop-mcp

Quick Start

Prerequisites

Python 3.10+
A SQLite database file (default: ./shop.db)

Local Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configure

Copy .env.example and set the database path:

cp .env.example .env
# Edit DATABASE_PATH to point to your SQLite file

Or set the environment variable directly:

export DATABASE_PATH=/abs/path/to/shop.db

Run the Server

python -m mcp_server.server

The server communicates over stdin/stdout using the MCP stdio transport. You don't interact with it directly — an MCP client (e.g., Claude Desktop, your AI agent) connects to it.

MCP Client Configurations

Standard Python

Add this to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "DATABASE_PATH": "/abs/path/to/shop.db"
      }
    }
  }
}

Docker

First build the image:

docker build -t mcp-shop:latest .

Then configure your MCP client:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/abs/path/to/shop.db:/app/shop.db",
        "-e", "DATABASE_PATH=/app/shop.db",
        "mcp-shop:latest"
      ]
    }
  }
}

Docker Compose

docker compose up -d

Tools

`list_tables`

Lists all user tables and views in the database (excludes internal sqlite_* tables).

Parameters: none

Returns:

{
  "tables": ["customers", "orders", "order_items", "products"],
  "count": 4
}

`describe_table`

Describes the schema of a table: columns, foreign keys, row count, and the CREATE statement.

Parameters:

table (string, required): Name of the table to describe.

Returns:

{
  "table": "customers",
  "columns": [
    {"cid": 0, "name": "id", "type": "INTEGER", "notnull": 0, "default": null, "pk": 1},
    {"cid": 1, "name": "first_name", "type": "TEXT", "notnull": 1, "default": null, "pk": 0}
  ],
  "foreign_keys": [],
  "row_count": 150,
  "sql": "CREATE TABLE customers (...)"
}

`query_database`

Executes a read-only SQL query with pagination support.

Parameters:

sql (string, required): A single read-only SQL statement (SELECT, WITH, EXPLAIN, or read-only PRAGMA).
limit (integer, optional): Maximum rows to return. Default: 100. Max: 1000.
offset (integer, optional): Number of rows to skip. Default: 0.

Returns:

{
  "columns": ["id", "first_name"],
  "rows": [{"id": 1, "first_name": "Alice"}, {"id": 2, "first_name": "Bob"}],
  "row_count": 2,
  "truncated": false,
  "limit": 100,
  "offset": 0
}

When truncated is true, more rows are available — increase offset to fetch the next page.

Security

The server implements defense-in-depth to guarantee read-only access:

Layer 1: SQLite Connection (URI read-only mode)

The database is opened with file:<path>?mode=ro, which prevents writes at the SQLite engine level. Additionally, PRAGMA query_only = ON is set on every connection.

Layer 2: SQL Query Validator (`security.py`)

Before any query reaches SQLite, it passes through a multi-stage validator:

String literal stripping: String literals ('...', "...") are replaced with placeholders so keywords inside data (e.g., a product named "Deleted Item") don't trigger false positives.
Comment detection: SQL comments (--, /* */) are rejected to prevent comment-based bypasses.
Multi-statement rejection: Any semicolon (;) is rejected, preventing stacked queries.
Keyword analysis: The first real statement keyword must be SELECT, WITH, EXPLAIN, or PRAGMA. Destructive keywords (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, REPLACE, TRUNCATE, ATTACH, DETACH, VACUUM, etc.) are blocked.
PRAGMA validation: Read-only PRAGMAs (table_info, database_list, etc.) are allowed. Any PRAGMA with an assignment (=) or in the mutating-PRAGMA blocklist (journal_mode, synchronous, foreign_keys, etc.) is rejected.

Layer 3: EXPLAIN Opcode Inspection

As a final defense, the query is run through SQLite's own parser via EXPLAIN <query>. The resulting opcode stream is inspected for write opcodes (OpenWrite, Insert, Delete, Create, Drop, etc.) and write-transaction flags. If any are found, the query is rejected.

Layer 4: Sanitized Error Messages

All errors returned to the client are sanitized — filesystem paths and internal details are stripped to prevent information leakage.

Testing

Tests use temporary/in-memory databases only — never the production shop.db.

# Run all tests
python -m pytest

# Run with verbose output
python -m pytest -v

# Run a specific test file
python -m pytest tests/test_security.py

Test Coverage

Test File	Coverage
`tests/test_security.py`	76 tests: valid queries, destructive statement rejection, PRAGMA validation, multi-statement rejection, comment bypass prevention, string literal handling
`tests/test_db.py`	20 tests: read-only enforcement, table listing, schema description, pagination, truncation, all 8 benchmark queries
`tests/test_server.py`	9 tests: MCP tool discovery, tool calls via SDK client, destructive query rejection, pagination, 7 benchmark queries via tools, stderr/no-stdout-pollution guard

Static Analysis

# Type checking
python -m mypy

# Linting
python -m ruff check src/ tests/

Project Structure

.
├── .env.example          # Environment variable template
├── Dockerfile            # Docker containerization
├── docker-compose.yml    # Docker Compose config
├── pyproject.toml        # Package config, deps, tool settings
├── README.md             # This file
├── shop.db               # The SQLite database (not included in tests)
├── src/mcp_server/
│   ├── __init__.py
│   ├── config.py         # Configuration (DATABASE_PATH, limits, URI builder)
│   ├── db.py             # Read-only Database class with introspection + query
│   ├── security.py       # SQL validator (multi-layer defense-in-depth)
│   ├── server.py         # MCP server entrypoint (stdio transport)
│   ├── tools.py          # MCP tool definitions and handlers
│   └── py.typed          # PEP 561 marker
└── tests/
    ├── __init__.py
    ├── test_db.py        # Database layer + benchmark tests
    ├── test_security.py  # Query validator tests
    └── test_server.py    # MCP server/tool tests

Benchmark Tasks

The server's tools enable an AI agent to perform these analytical tasks (validated by tests against a controlled fixture database):

Table Discovery: list_tables + describe_table — list all tables and describe schemas.
Filtered Count: query_database with SELECT COUNT(*) FROM customers WHERE country = 'Germany'.
Country Aggregation: SELECT country, COUNT(*) ... GROUP BY country ORDER BY ... DESC LIMIT 1.
Customer LTV: Join customers + orders, SUM(total_amount), order by total.
Product Performance: Join order_items + products, aggregate by quantity and revenue, LIMIT 5.
Category Aggregation: Traverse order_items → products → category, aggregate revenue, LIMIT 3.
Date Filtering: SUM(total_amount) WHERE substr(order_date,1,4) = '2025'.
Order Aggregation: Join customers + orders, COUNT(o.id), order by count.

Configuration

Environment Variable	Default	Description
`DATABASE_PATH`	`./shop.db`	Path to the SQLite database file
`ROW_LIMIT`	`100`	Default row limit for query results (max 1000)

License

This project is provided as-is for demonstration purposes.

Available Tools

3 tools

describe_tableA

Describe the schema of a table: columns (name, type, notnull, default, primary key), foreign keys, row count, and the CREATE statement. Returns JSON with 'table', 'columns', 'foreign_keys', 'row_count', 'sql'. Read-only.

ParametersJSON Schema

Name	Required	Description	Default
`table`	Yes	Name of the table to describe.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the operation is read-only and details the return structure (JSON with specific keys). It does not mention error handling, permission requirements, or side effects, but for a read-only introspection tool these are minor. The description adds value by describing what information is returned, beyond what annotations would provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, dense sentence that front-loads the primary purpose and then enumerates the exact components and return keys. Every phrase adds information—no filler or redundancy. It is concise yet comprehensive, structuring the behavior clearly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description explicitly lists the return keys ('table', 'columns', 'foreign_keys', 'row_count', 'sql') and details column attributes. This fully equips an agent to interpret the result. It also covers the read-only nature and the scope (schema description). For a single-parameter introspection tool, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter, with the schema saying 'Name of the table to describe.' The description adds no additional meaning beyond that—it doesn't explain how to obtain valid table names (e.g., via list_tables) or any format constraints. Since the schema already fully documents the parameter, the description's contribution is minimal, matching the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Describe') and resource ('a table') with clear detail on what is covered: columns with type/notnull/default/PK, foreign keys, row count, and the CREATE statement. It is unambiguous and distinct from siblings like list_tables (which presumably lists table names) and query_database (which executes queries). The purpose is immediately clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly defines when to use it: when you need schema metadata for a specific table. It states it is 'Read-only', which implies it is safe for inspection. However, it does not explicitly contrast with list_tables or query_database, nor mention any exclusions (e.g., when to avoid it). Since the usage context is clear but alternatives are not named, a score of 4 is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesA

List all user tables and views in the database (excludes internal sqlite_* tables). Returns a JSON object: {"tables": ["table1", "table2", ...], "count": N}. This is a read-only operation.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It explicitly states 'This is a read-only operation,' disclosing it has no side effects. It also discloses the exclusion of internal tables and the exact return format. This is good behavioral disclosure for a simple list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. Purpose is front-loaded, return format is given, and the read-only note is appended. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no params and no output schema, the description fully covers what the agent needs: the scope (user tables/views), the exclusion of internal tables, and the exact JSON return shape. Nothing missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema is trivially covered at 100%. Per the baseline for 0 params, the description doesn't need to add parameter semantics, and it doesn't. No gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all user tables and views, excluding internal sqlite_* tables. This specific verb+resource combination distinguishes it from siblings like describe_table (specific table) and query_database (run queries).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use it: to get an overview of all tables/views. However, it does not explicitly mention alternatives or when not to use it, but the contrast with siblings is obvious enough. Lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_databaseA

Execute a read-only SQL query (SELECT / WITH / EXPLAIN / read-only PRAGMA) against the database. Destructive statements (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, etc.), multi-statement queries, and SQL comments are rejected. Results are paginated: a default row limit of 100 is applied (max 1000). Use 'limit' and 'offset' for pagination. If 'truncated' is true, more rows are available. Returns JSON: {"columns": [...], "rows": [{...}], "row_count": N, "truncated": bool, "limit": N, "offset": N}.

ParametersJSON Schema

Name	Required	Description
`sql`	Yes	A single read-only SQL statement.
`limit`	No	Maximum rows to return (default 100).
`offset`	No	Number of rows to skip for pagination.

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for disclosing behavior, and it does so thoroughly. It states the read-only nature, rejection of destructive statements, pagination behavior (default limit of 100, max 1000, offset support), and signals when more rows exist (truncated flag). The return format is fully specified, which is exceptional given the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, front-loaded with the core purpose and restrictions, then pagination, then output format. Every sentence contributes essential information with zero redundancy or fluff. It is structured so the most critical constraints (read-only, rejected statements) appear first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a SQL query tool with no output schema and no annotations, the description is remarkably complete. It explains the allowed statements, the rejection rules, pagination mechanics, and the exact JSON response structure. An agent has everything required to call the tool correctly and interpret results. Error handling isn't mentioned, but that is a minor omission given the breadth of what is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%—all three parameters have descriptive text in the schema. The description adds context around pagination (use limit/offset) but does not introduce new semantic information beyond what the schema already provides. The default limit and max are already in the schema, so the description's added value is limited to reinforcing the pagination workflow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Execute') and resource ('read-only SQL query') and enumerates the allowed statement types (SELECT, WITH, EXPLAIN, read-only PRAGMA). It clearly distinguishes itself from sibling tools by focusing on arbitrary query execution rather than metadata listing, so an agent can tell it apart immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear the tool is for read-only queries and explicitly lists what is rejected (destructive statements, multi-statement, comments). It does not name sibling tools or give explicit 'when to use vs. alternatives' guidance, but the context is unambiguous—if you need to run a SELECT or similar, use this. The exclusion criteria are, however, implied rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

3 tool updatesv1.0.0Aug 23, 2026
- First observeddescribe_table
- First observedlist_tables
- First observedquery_database

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored 2026-08-23 23:40 across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: listing tables/views, describing schema details, and executing read-only queries. There is no functional overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow the same snake_case verb_noun pattern (list_tables, describe_table, query_database), offering a consistent and predictable naming convention.

Tool Count5/5

With only 3 tools, the server is well-scoped for a read-only SQLite interface. Each tool covers a distinct and essential operation, and the count is ideal for the purpose.

Completeness5/5

For a read-only SQLite server, the toolset is complete: listing tables, describing schema, and querying data with pagination cover all typical use cases. Even edge cases like EXPLAIN and read-only PRAGMAs are supported via query_database.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

wgong-sqlite-mcp-server
ai.smithery
Explore, query, and inspect SQLite databases with ease. List tables, preview results, and view det…
Databases Developer Tools
21
QueryBearOAuth
io.github.spencerpauly
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Databases RAG Systems
2
Plato's Kallipolis A
io.github.handongzhen101-jpg
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Agent Orchestration AI & Machine Learning
61
Dataassist-IOOAuth
io.github.DataAssistIO
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search Databases
2

Related MCP Servers

mcp-to-db
Databases RAG Systems
jorgepvenegas
F
license
Not graded
quality
C
maintenance
Exposes any SQLite database as read-only MCP tools for AI assistants, enabling listing tables, describing schemas, and running SELECT queries with filtering, ordering, and pagination.
Updated 2 months ago (2026-07-17 04:31 UTC)
-
shop-mcp
Databases
stalexsm
F
license
A
quality
C
maintenance
Enables AI agents to safely explore and query a SQLite database in read-only mode, allowing them to inspect schema and run analytical SQL queries without risking data modification.
Updated 21 days ago (2026-08-23 15:32 UTC)
3
-
sql-guard-mcp
Databases Security
egoring
A
license
Not graded
quality
B
maintenance
Enables AI agents to safely query and explore SQLite databases through read-only, guard-protected tools that block writes, sensitive table access, and runaway queries.
Updated 12 days ago (2026-09-02 06:54 UTC)
1
MIT
shop-analytics-mcp
Databases Developer Tools
yuzislav
A
license
Not graded
quality
C
maintenance
Enables AI agents to read-only query a SQLite database, inspect schema and table summaries, and execute SELECT queries with pagination through MCP.
Updated 13 days ago (2026-08-31 13:52 UTC)
MIT

MCP SQLite Server (Read-Only)

Features

Quick Start

Prerequisites

Local Setup

Configure

Run the Server

MCP Client Configurations

Standard Python

Docker

Docker Compose

Tools

list_tables

describe_table

query_database

Security

Layer 1: SQLite Connection (URI read-only mode)

Layer 2: SQL Query Validator (security.py)

Layer 3: EXPLAIN Opcode Inspection

Layer 4: Sanitized Error Messages

Testing

Test Coverage

Static Analysis

Project Structure

Benchmark Tasks

Configuration

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`list_tables`

`describe_table`

`query_database`

Layer 2: SQL Query Validator (`security.py`)