01
Policy layer
Read-only by design
Every query is checked before SQLite sees it. Write keywords and non-SELECT statements are rejected with a direct error.
Read-only SQLite access for AI agents
Your database.
Now agent-readable.
A focused Model Context Protocol server that lets Claude Desktop and custom agents inspect, query, and reason over local SQLite databases without write access.
06MCP tools
100row response cap
00write operations
01$ claude mcp add database-mcp .venv/bin/python mcp/src/server.py
02connected database-mcp-server v1.0.0
03→ tools/call list_databases
04← { "databases": ["sample.db"] }
05→ tools/call run_select
06· SELECT name, price FROM products
07· ORDER BY price DESC LIMIT 3
08allowed read-only policy passed
09
01 / OVERVIEW
A small bridge with a strict boundary.
The server translates an agent's tool calls into controlled SQLite operations. It handles database discovery, schema inspection, query execution, and query planning while keeping destructive SQL outside the boundary.
02
Database discovery
One file or many
Scan a directory for `.db` and `.sqlite` files, or mount an explicit path using environment variables.
03
Query intelligence
Inspect before asking
Agents can list tables, inspect column types, and run `EXPLAIN QUERY PLAN` before executing a final query.
02 / ARCHITECTURE
Follow the request.
From natural-language question to bounded SQLite response.
A
AI client
Claude Desktop or agent
stdio / JSON-RPC→
B
MCP router
Validates and dispatches
tools/call→
C
Safety layer
SELECT-only policy
safe SQL→
D
SQLite
Local database files
TOOL CALL / list_databases
Find available data sources
The agent begins by discovering every database currently mounted through `DB_DIR` or `DB_PATH`.
{
"method": "tools/call",
"params": {
"name": "list_databases",
"arguments": {}
}
}
03 / QUICK START
Connect in minutes.
Choose the route that fits your environment.
- 01Clone the repository
Bring the bridge into your local workspace.
git clone https://github.com/buvaneswaraneb/mcp-database-bridge.git - 02Run automated setup
Creates the virtual environment, installs dependencies, and updates Claude Desktop.
chmod +x setup.sh && ./setup.sh - 03Restart Claude Desktop
Completely quit the app, reopen it, then verify `database-mcp` is connected.
READY TO QUERY
- 01Clone and enter the project
Use PowerShell or Command Prompt.
git clone https://github.com/buvaneswaraneb/mcp-database-bridge.git - 02Run the setup script
Installs the Python environment and configures Claude Desktop.
setup.bat - 03Restart Claude Desktop
Close the application completely before reopening it.
READY TO QUERY
CLAUDE CODE
Register the MCP server using the Python executable from your virtual environment.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
claude mcp add database-mcp .venv/bin/python mcp/src/server.py
ENVIRONMENT
Mount a directory of databases or a single explicit database path.
DB_DIR=/absolute/path/to/databases
DB_PATH=/absolute/path/to/example.db
04 / TOOL REFERENCE
Six focused capabilities.
Everything an agent needs to discover, inspect, and safely query local SQLite data.
open_database_manager
Launch the FastAPI-powered browser manager for uploading and deleting database files.
{ }list_databases
Return the names of all `.db` and `.sqlite` files available to the bridge.
{ }list_tables
List tables inside the selected database.
{ "db_name": "sample.db" }get_schema
Inspect names, types, and nullability for every column in a table.
{ "table_name": "orders" }run_select
Execute a validated `SELECT` statement and return up to 100 rows.
{ "query": "SELECT * FROM orders" }explain_query
Return SQLite's execution plan to help diagnose and optimize a query.
{ "query": "SELECT * FROM orders" }
05 / DEBUGGING
Test the safety boundary.
Enter a query to preview how the bridge's read-only guard will classify it.
QUERY SAFETY PLAYGROUND waiting for query
200 / ALLOWED
Read-only policy passed.
This query begins with SELECT and contains no blocked write keywords.
TROUBLESHOOTING INDEX
Find the fault faster.
Confirm `DB_DIR` points to a readable directory containing `.db` or `.sqlite` files. If using `DB_PATH`, make sure it is an absolute path to an existing file.
DB_DIR=/absolute/path/to/sample_dataWhen more than one database is mounted, include `db_name` in tool arguments so the bridge can resolve the correct file.
{ "db_name": "sample.db" }Use absolute paths in `claude_desktop_config.json`, verify the virtual environment exists, and completely restart Claude Desktop after changing configuration.
claude mcp listThe guard rejects queries containing `INSERT`, `UPDATE`, `DELETE`, `DROP`, `CREATE`, `ALTER`, `TRUNCATE`, or `PRAGMA`. Keep the statement to a direct `SELECT` query.
SELECT * FROM products LIMIT 20;Start the manager directly and inspect the terminal output. Ensure port `8000` is free and all requirements are installed.
python -m uvicorn mcp.src.web:app --port 8000No matching debugging tip found.