easy-sqlite-mcp
A Model Context Protocol (MCP) server implemented in Node.js and TypeScript, designed to enable LLMs to interact directly with SQLite databases.
This project uses Node.js, TypeScript, the official MCP SDK, and better-sqlite3. It runs over stdio, so it can be used directly by MCP clients such as Claude Desktop, Codex, and OpenCode.
Features
- SQLite connection management for manual and fixed startup modes
- Read-only query tool for data retrieval
- Execute tool for data modification and schema statements
- Schema discovery tools for tables, views, indexes, and triggers
- Lightweight, synchronous SQLite access powered by
better-sqlite3
better-sqlite3 in this project requires Node.js 22 or newer. Use Node.js 22 LTS for the most reliable prebuilt-binary availability on Windows.
Requirements
- Node.js 22 or newer (Node.js 22 LTS recommended)
- npm
- A reachable SQLite database file
Installation
Run the server directly with npx:```bash
npx -y easy-sqlite-mcp
For local development after cloning the repository:```bash
cd easy-sqlite-mcp
npm install
npm run build
Configuration
Configure the server with environment variables in your MCP client configuration or shell environment.
| Variable | Required | Default | Description |
|---|---|---|---|
SQLITE_PATH |
No | - | Absolute or relative path to a SQLite database file. When set, the server starts in fixed mode |
Example shell configuration:```bash
SQLITE_PATH=/absolute/path/to/database.sqlite npx -y easy-sqlite-mcp
In PowerShell:```powershell
$env:SQLITE_PATH = "C:\data\database.sqlite"
npx -y easy-sqlite-mcp
The server communicates over stdio and is normally launched by an MCP client rather than run manually.
If you are unsure how a tool should be used, or an operation fails, call sqlite_manual first. It returns the built-in manual with safe usage rules, placeholder guidance, and lifecycle notes.
Modes
Easy SQLite MCP supports two startup modes. The server description is generated at startup so MCP clients and agents can clearly understand which mode is active.
Manual Mode
Manual mode is used when SQLITE_PATH is not provided.
In this mode, the agent must explicitly open and close a database:
- Call
sqlite_open(path)before using database tools. - Use query, execute, and schema discovery tools.
- Call
sqlite_closewhen finished.
Only one SQLite database file can be open at a time. Opening another file closes the previous connection first.
Server description:```text
Manual: This is a SQLite tool. Before using it, call sqlite_open(path) to open a database file. After use, call sqlite_close to close it. Only one database file can be open at a time.
Available tools in Manual mode:
- `sqlite_open`
- `sqlite_close`
- `sqlite_status`
- `sqlite_query`
- `sqlite_execute`
- `sqlite_list_tables`
- `sqlite_describe_table`
### Fixed Mode
Fixed mode is used when `SQLITE_PATH` is provided as an environment variable.
In this mode, the server automatically opens the configured SQLite database during startup. The agent does not need to call `sqlite_open`, and connection switching is disabled.
Server description:```text
Fixed: This is a SQLite tool connected to Path:<SQLITE_PATH>
Available tools in Fixed mode:
sqlite_statussqlite_querysqlite_executesqlite_list_tablessqlite_describe_table
Claude Desktop Example
Manual mode:```json
{
"mcpServers": {
"easy-sqlite-mcp": {
"command": "npx",
"args": ["-y", "easy-sqlite-mcp"]
}
}
}
Fixed mode example:```json
{
"mcpServers": {
"easy-sqlite-mcp": {
"command": "npx",
"args": ["-y", "easy-sqlite-mcp"],
"env": {
"SQLITE_PATH": "/absolute/path/to/database.sqlite"
}
}
}
}
Restart Claude Desktop after updating the configuration.
Codex config.toml Example
Manual mode:```toml
[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true
Fixed mode example:```toml
[mcp_servers.easy-sqlite-mcp]
args = ["-y", "easy-sqlite-mcp"]
command = "npx"
enabled = true
[mcp_servers.easy-sqlite-mcp.env]
SQLITE_PATH = "/absolute/path/to/database.sqlite"
OpenCode opencode.jsonc Example
Manual mode:```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"easy-sqlite-mcp": {
"type": "local",
"command": ["npx", "-y", "easy-sqlite-mcp"],
"enabled": true
}
}
}
Fixed mode example:```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"easy-sqlite-mcp": {
"type": "local",
"command": ["npx", "-y", "easy-sqlite-mcp"],
"enabled": true,
"environment": {
"SQLITE_PATH": "/absolute/path/to/database.sqlite"
}
}
}
}
Available Tools
| Tool | Description |
|---|---|
sqlite_manual |
Return the built-in manual. Use this first when you are unsure how to use SQLite tools or need help diagnosing an operation error |
sqlite_open |
Open a SQLite database file. Manual mode only |
sqlite_close |
Close the current database connection. Manual mode only |
sqlite_status |
Return connection status and current database summary |
sqlite_query |
Execute a read-only SELECT query |
sqlite_execute |
Execute a write or modification SQL statement |
sqlite_list_tables |
List all user tables in the database |
sqlite_describe_table |
Describe the schema of a table |
Manual Mode Notes
- Use
sqlite_open(path)before calling query or execute tools. - Use
sqlite_closewhen finished. - Only one database file can be open at a time.
- Use
sqlite_manualwhen you need lifecycle or placeholder guidance.
Development```bash
npm run build
npm run dev
npm test
```
License
MIT. See LICENSE.md.
