MCP SQLite Server
Provides tools for exploring and querying a SQLite database, including listing tables, describing schemas, running safe read-only SQL queries, and optionally executing guarded write queries when enabled.
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., "@MCP SQLite Server Show me the tables in this database and their row counts."
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.
🗄️ MCP SQLite Server
Day 10 of 30 Days of AI Agents: a Model Context Protocol server that lets any AI app (Claude Desktop, Cursor, your own agent) explore a SQLite database with safe, read-only SQL tools.

The repo has two parts:
The MCP server (
src/index.ts): exposes a SQLite database as tools. Plug it into any MCP client.A demo agent (
npm run chat): starts the server as a child process, connects to it as an MCP client, and lets an LLM answer questions with it.
What it shows
MCP (Model Context Protocol): write tools once and every MCP client can discover and call them. The server registers tools, a resource (
sqlite://schema) and a prompt (explore-data).Tool discovery: the agent has no SQLite code. It calls
tools/list, converts the JSON Schemas to OpenAI function tools, and forwards the model's calls withtools/call.Guardrails for model-written SQL, in layers:
read_queryonly acceptsSELECT/WITH.SQLite itself must report the prepared statement as read-only (
stmt.readonly), which catches writes hidden inside a CTE.The connection is opened read-only unless you set
ALLOW_WRITES=true.Stacked statements are refused and results are capped at
MAX_ROWS.
Errors the model can recover from: a blocked query comes back as an MCP tool error, so the agent explains instead of crashing.
Opt-in writes:
write_queryonly exists whenALLOW_WRITES=true, accepts INSERT/UPDATE/DELETE only, and refuses UPDATE/DELETE withoutWHERE.Swappable providers: Gemini (free tier, default), Groq, OpenAI or Anthropic through one OpenAI-compatible client.
Tests without API keys: an in-memory MCP client/server pair plus a scripted LLM. 35 tests run in CI for free.
Related MCP server: sqlite-mcp-local
Quick start
Needs Node.js 22 or newer.
git clone https://github.com/obiokoye/mcp-sqlite-server.git
cd mcp-sqlite-server
npm install
cp .env.example .env # optional: add a free Gemini key from https://aistudio.google.com/apikey
npm run chatThe first run creates data/shop.db, a small bakery's sample orders (customers, products, orders, order_items). Ask things like:
What's in this database?Who are our top 3 customers by total spend?Which product category sold the most units in October?Delete all the cancelled orders(watch the server refuse)
One-shot mode: npm run chat -- "Who are our top 3 customers by total spend?"
Windows
git clone https://github.com/obiokoye/mcp-sqlite-server.git
cd mcp-sqlite-server
npm install
copy .env.example .env
npm run chatbetter-sqlite3 ships prebuilt binaries for Windows. If npm install tries to compile it and fails, update to the current Node.js LTS from nodejs.org and run npm install again.
Demo mode
With no API key, npm run chat switches to demo mode automatically and prints Demo mode: scripted AI replies. You can also force it with DEMO_MODE=true or npm run chat -- --demo.
In demo mode only the "model" is scripted: the tool calls are real. They go over stdio to the real MCP server and run against the real database, and the scripted answers are built from the rows that come back. The scripted client is the same ScriptedLlm the tests use.
Use it from Claude Desktop (or any MCP client)
Build once, then point your client at dist/index.js:
npm run buildclaude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"sqlite": {
"command": "node",
"args": ["C:\\path\\to\\mcp-sqlite-server\\dist\\index.js"],
"env": { "DB_PATH": "data/shop.db" }
}
}
}Restart Claude Desktop and ask it about your data. To poke at the server by hand, run npm run inspect (opens the official MCP Inspector).
Server settings
Variable | Default | What it does |
|
| SQLite file to serve, relative to the project folder. The default file is created with sample data if missing. |
|
|
|
|
| Row cap per |
Tools, resource and prompt
Name | Kind | Description |
| tool | Every table with its row count |
| tool | Columns, types, primary key and foreign keys |
| tool | One |
| tool | Only when |
| resource |
|
| prompt | Turns a business question into a guided, tool-using prompt |
Switching providers (demo agent)
| Key variable | Default model | Free tier |
|
|
| ✅ |
|
|
| ✅ |
|
|
| ❌ |
|
|
| ❌ |
Override the model with LLM_MODEL=....
Project structure
src/
index.ts # MCP server entry point (stdio transport)
server.ts # registers tools, the schema resource and the prompt
db.ts # SQLite access + SQL guardrails
seed.ts # sample bakery data (npm run seed)
config.ts # server settings from env
chat.ts # terminal chat: spawns the server, connects an MCP client
agent/
agent.ts # agent loop: MCP tools -> LLM -> MCP tool calls
llm.ts # LLM interface + OpenAI-compatible client
providers.ts # provider table, demo-mode fallback
scripted.ts # ScriptedLlm (tests + demo mode)
demo-scenarios.ts # scripted demo conversations
tests/ # vitest, no network or API key neededExtending it
Add a tool: write the function in
src/db.ts, thenserver.registerTool(...)insrc/server.tswith a zodinputSchema. Every MCP client (and the demo agent) picks it up throughtools/listwith no other changes.Serve your own database: set
DB_PATH=path/to/your.db. The server opens it read-only.Try another client: the agent in
src/agent/agent.tsworks with any MCP server. Change the command inchat.tsto start a different one.
Scripts
Command | What it does |
| Demo agent in the terminal |
| Run the MCP server from source (stdio) |
| Compile to |
| Recreate |
| Open the MCP Inspector against the built server |
| Run the tests |
New to TypeScript or MCP? See LEARN.md, which walks through this codebase in Laravel terms.
MIT © Nicholas Okoye
Available Tools
3 toolsdescribe_tableDescribe tableBRead-only
Show a table's columns (name, type, primary key, not null) and foreign keys.
Inputs: table (required).
list_tablesList tablesARead-only
List every table in the database with its row count.
Inputs: no named parameters.
read_queryRun a read-only SQL queryARead-only
Run ONE SQLite SELECT (or WITH ... SELECT) statement and get rows back as JSON. At most 100 rows are returned; use LIMIT, GROUP BY and aggregates for large tables.
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a clearly distinct step of database exploration: enumerating tables, inspecting a single table's schema, and running a query. There is no overlap between schema metadata retrieval and row retrieval, and the descriptions reinforce the boundaries.
All three names follow a clean verb_noun snake_case pattern (list_tables, describe_table, read_query), with distinct verbs that map directly to their actions.
Three tools is minimal but well-matched to a narrow read-only database inspection purpose; nothing is redundant. It sits at the thin edge of the ideal range, so a user wanting write access would find the surface small.
The read path is well covered (discover tables, inspect schema, query data), but there is no way to mutate data or run non-SELECT statements such as INSERT, UPDATE, DELETE, or DDL. Agents can explore but cannot modify the database, which is a notable gap for a general SQLite server.
Maintenance
Related MCP Connectors
Explore, query, and inspect SQLite databases with ease. List tables, preview results, and view det…
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Related MCP Servers
- AlicenseAqualityDmaintenanceRead-only SQLite database explorer for MCP clients. Allows discovery of tables and columns via resources and running SELECT queries via a tool.2MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only querying of a local SQLite database via MCP, with tools to list tables, retrieve schema, and execute SELECT/WITH/EXPLAIN queries.-
- AlicenseNot gradedqualityDmaintenanceEnables read-only access to SQLite databases via MCP, with tools for browsing tables, schemas, and executing SELECT queries securely.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to interact with pre-registered SQLite databases using aliases, supporting schema inspection, read-only queries, and data modification via tools.70 npmMIT