SQLite

This MCP server lets AI agents interact with SQLite databases by reading, writing, and inspecting schema while keeping a self-documented memory of the database structure. It supports automatic query logging and a dedicated meta-table to help agents maintain context across sessions.

How to use

You connect to a SQLite database through an MCP client and then perform read and write operations via dedicated tools. The server exposes a lightweight set of actions that let you connect to a database file, run queries, inspect tables, and retrieve the full schema. When you connect, the server can provide guided best practices and notes to help agents understand the database rules.

How to install

Prerequisites: ensure you have Node.js v14 or higher installed on your system.

Option 1: Local Installation (recommended for development) follow these steps to run the MCP server from source.

git clone https://github.com/u1pns/sqlite-mcp.git
cd sqlite-mcp
npm install

// Example configuration for Gemini CLI
{
  "mcpServers": {
    "sqlite-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/sqlite-mcp/index.js"],
      "env": {
        "SQLITE_DB_PATH": "/absolute/path/to/your/database.sqlite"
      }
    }
  }
}

Option 2: Using npx (no installation required) run directly from the repository without cloning.

// Gemini CLI example with npx
{
  "mcpServers": {
    "sqlite-mcp": {
      "command": "npx",
      "args": ["-y", "github:u1pns/sqlite-mcp"],
      "env": {
        "SQLITE_DB_PATH": "/absolute/path/to/my/db.sqlite"
      }
    }
  }
}

Configuration and usage notes

Connect to a database file using the provided tools and keep a minimal, self-documenting layer in the database via the _architecture_notes table. Architects must insert notes describing why a table exists and how it works. Workers read these notes to understand system rules without long prompts.

The server logs all queries to daily files inside a log/ directory. You can use the logs to audit activity and troubleshoot issues.

Tools and capabilities

The server exposes a small, focused toolkit to work with SQLite databases.

• connect_database Connect to a specific SQLite database file. Returns custom guidance and best practices after a successful connection.

• read_query Execute a SELECT query or PRAGMA to fetch data.

• write_query Execute data-changing statements like INSERT, UPDATE, DELETE, CREATE, and DROP.

• list_tables List all tables in the current database.

• describe_table Get the schema for a specific table.

• get_schema_ddl Return the full CREATE TABLE statements for the entire database.

• get_custom_instructions Retrieve the content of instructions.md for re-reading best practices.

Security and notes

Only connect to trusted databases and manage access via your MCP client configuration. The server assumes absolute database paths for safety, and relative paths are created inside the MCP server directory.

Troubleshooting

If you encounter connection issues, verify the SQLITE_DB_PATH is correct and the database file exists. Check the log/ directory for recent query logs to identify failing statements. Ensure Node.js v14+ is installed and that the MCP server process has permission to read and write to the database file.

Available tools

connect_database

Connect to a specific SQLite database file. Automatically returns custom instructions and best practices (from instructions.md) upon successful connection.

read_query

Execute a SELECT query or PRAGMA to fetch data.

write_query

Execute a write query such as INSERT, UPDATE, DELETE, CREATE, and DROP.

list_tables

List all tables in the current database.

describe_table

Get the schema for a specific table.

get_schema_ddl

Return the full CREATE TABLE statements for the entire database.

get_custom_instructions

Retrieve the content of instructions.md for best practices.