# easy-sqlite-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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:

1. Call `sqlite_open(path)` before using database tools.
2. Use query, execute, and schema discovery tools.
3. Call `sqlite_close` when 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_status`
- `sqlite_query`
- `sqlite_execute`
- `sqlite_list_tables`
- `sqlite_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_close` when finished.
- Only one database file can be open at a time.
- Use `sqlite_manual` when you need lifecycle or placeholder guidance.

## Development

```bash
npm run build
npm run dev
npm test
```

## License

MIT. See [LICENSE.md](LICENSE.md).