mcp-sqlite-tools-plus

mcp-sqlite-tools-plus

A Model Context Protocol (MCP) server that givesAI agents safe, structured access to local SQLite databases: full CRUD, schemaintrospection, table relations (foreign keys), generated/computed columns, andmulti-format import/export — CSV, JSON and XLSX.

Fork notice. This is a fork ofspences10/mcp-sqlite-tools byScott Spence (MIT). It adds JSON and XLSX import/export tools on top of theoriginal CSV support, plus hardening guidance. All original tooling and creditbelong to the upstream project. The complete per-tool reference from upstream ispreserved in docs/UPSTREAM_README.md.

Why this exists

For a non-technical user who only talks to an agent, the agent can do everything aspreadsheet does — and more — by talking to this server: read, create, update anddelete rows, relate tables, compute totals automatically, and hand back a CSV / JSON/ Excel file to share. The deterministic work (queries, format conversion) is doneby the server, not improvised by the model.

Features

• CRUD over any SQLite database via SQL or dedicated tools.
• Schema introspection — list_tables, describe_table, export_schema.
• Relations — foreign keys are enforced (PRAGMA foreign_keys = ON on everyconnection), so referential integrity is real, not optional.
• Generated columns — e.g. total GENERATED ALWAYS AS (unit_cost * quantity)via execute_schema_query; the engine keeps them in sync automatically.
• Import / export in CSV, JSON and XLSX (export accepts a table or aread-only query; import creates the table from headers/keys when missing).
• Safety by design — connection pooling, prepared statements, transactionalbulk inserts, identifier quoting, and path confinement.
• Tools are labelled SAFE / SCHEMA CHANGE / DESTRUCTIVE / FILE WRITE so anagent (and its permission layer) can reason about risk.

Requirements

• Node.js >= 20
• A package manager. pnpm is recommended (the repo pins it via packageManager),but npm works too.

Installation

Option A — npm (recommended)

The package is published on npm asmcp-sqlite-tools-plus.No clone or build needed — your MCP client runs it via npx (see Configuration).To try it standalone:

npx -y mcp-sqlite-tools-plus

Option B — from source

git clone https://github.com/MauricioPerera/mcp-sqlite-tools-plus.git
cd mcp-sqlite-tools-plus

# with pnpm (recommended)
corepack enable
pnpm install
pnpm build        # outputs dist/index.js

# or with npm
npm install
npm run build

The built entry point is dist/index.js.

Configuration

Add the server to your MCP client. Example for Claude Desktop(claude_desktop_config.json).

Using npm (Option A):

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "mcp-sqlite-tools-plus"],
      "env": {
        "SQLITE_DEFAULT_PATH": "/absolute/path/to/your/databases",
        "SQLITE_ALLOW_ABSOLUTE_PATHS": "false",
        "SQLITE_BUSY_TIMEOUT": "60000",
        "SQLITE_BACKUP_PATH": "/absolute/path/to/your/backups",
        "DEBUG": "false"
      }
    }
  }
}

On Windows, if npx is not picked up directly, use"command": "cmd" with "args": ["/c", "npx", "-y", "mcp-sqlite-tools-plus"].

From source (Option B): set "command": "node" and"args": ["/absolute/path/to/mcp-sqlite-tools-plus/dist/index.js"], keeping thesame env block.

Replace the /absolute/path/... placeholders with paths on your machine. Restartthe MCP client after editing its config.

Environment variables

Hardening recommendation: SQLITE_ALLOW_ABSOLUTE_PATHS=false +SQLITE_DEFAULT_PATH set to a single dedicated folder is the most importantcontrol — it limits what the agent can reach.

The 5 performance PRAGMAs (journal_mode=WAL, synchronous=NORMAL,cache_size, foreign_keys=ON, temp_store=MEMORY) are applied automatically onevery connection and are not configurable via env.

Tool catalogue (26 tools)

Legend: ✓ read-only · ⚠️ writes data/schema/files.

Databases & maintenanceopen_database ✓ · create_database ⚠️ · close_database ✓ · list_databases ✓ ·database_info ✓ · backup_database ✓ · vacuum_database ✓

Schema & relationslist_tables ✓ · describe_table ✓ · create_table ⚠️ · drop_table ⚠️ ·export_schema ✓ · import_schema ⚠️ · execute_schema_query ⚠️ (DDL: foreignkeys, generated columns, indexes, …)

Query & dataexecute_read_query ✓ (SELECT/PRAGMA/EXPLAIN, parameterised, JOINs) ·execute_write_query ⚠️ · bulk_insert ⚠️

Transactionsbegin_transaction ⚠️ · commit_transaction ✓ · rollback_transaction ⚠️

Import / exportimport_csv ⚠️ · export_csv ⚠️ · import_json ⚠️ (new) ·export_json ⚠️ (new) · import_xlsx ⚠️ (new) · export_xlsx ⚠️ (new)

Export tools take exactly one of table or a read-only query. Import toolscreate the target table from the file's headers/keys when it does not exist andinsert rows inside a transaction with per-row error reporting.

See docs/UPSTREAM_README.md for the full per-toolparameter reference inherited from upstream.

Usage — for users

You talk to your agent in natural language; the agent calls the tools. Examples:

• "Import sales.xlsx into a table called sales." → import_xlsx
• "What columns does the orders table have?" → describe_table
• "Total revenue per category." → execute_read_query with a GROUP BY
• "Add an order for customer 3, 5 units at 9.99." → execute_write_query
• "Export the orders of June as an Excel file." → export_xlsx with a query
• "Make a total column that is price × quantity." → execute_schema_query with agenerated column

Relations and computed columns

CREATE TABLE customers (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL
);

CREATE TABLE orders (
  id INTEGER PRIMARY KEY,
  customer_id INTEGER NOT NULL,
  unit_cost REAL NOT NULL,
  quantity INTEGER NOT NULL,
  total REAL GENERATED ALWAYS AS (unit_cost * quantity) STORED,
  FOREIGN KEY (customer_id) REFERENCES customers(id)
);

total is computed by the engine (never inserted by hand), and inserting an orderwith a non-existent customer_id is rejected by the foreign key.

Usage — for AI agents

Guidance for an agent driving this server:

1. Discover before you query. Call list_tables, then describe_table on therelevant tables, to learn columns, types, foreign keys and indexes. Do not guessthe schema.
2. Respect the risk labels. Tools are tagged SAFE / SCHEMA CHANGE /DESTRUCTIVE / FILE WRITE. Confirm with the user before any non-SAFEoperation, and never issue UPDATE/DELETE without a WHERE clause.
3. Always parameterise. Use bound parameters in execute_read_query /execute_write_query; never interpolate user values into SQL strings.
4. Use transactions (begin_transaction … commit_transaction /rollback_transaction) for multi-step writes; use bulk_insert for batches.
5. Back up before destructive work. Call backup_database before schemachanges, mass updates or deletes.
6. Surface what you did. When returning a computed result, show the SQL you ranand/or the affected rows so the user can verify it.
7. Relations & totals belong in the schema. Prefer foreign keys and generatedcolumns over recomputing values in application/model logic.

Development

pnpm test          # run the vitest suite
pnpm build         # build dist/index.js
pnpm inspect       # run the MCP inspector against the built server

Security & privacy

• Set SQLITE_ALLOW_ABSOLUTE_PATHS=false and a dedicated SQLITE_DEFAULT_PATH toconfine the agent to one directory.
• Foreign keys are enforced on every connection.
• Identifiers are quoted and values are parameterised to avoid SQL injection.
• Keep backups (SQLITE_BACKUP_PATH) out of version control.

Credits & license

• Original project: spences10/mcp-sqlite-toolsby Scott Spence.
• Fork (mcp-sqlite-tools-plus, JSON/XLSX import-export + hardening) maintained byMauricioPerera.

Licensed under the MIT License — see LICENSE. The originalcopyright is retained as required by the license.