mcp-sqlite-tools

library0.0.17jsnpmunverified

The `mcp-sqlite-tools` package provides a Model Context Protocol (MCP) server designed to enable AI assistants and LLMs to safely and efficiently interact with local SQLite databases. Currently at version 0.0.17, it is under active development, indicating potential API changes before a stable 1.0 release. It offers comprehensive features for database management, table and query operations (read, write, schema), transaction control (with savepoints), schema export/import, and database maintenance like backups and vacuuming. Key differentiators include built-in security features such as query classification, path validation, input validation using Valibot, and advanced connection pooling. The server explicitly categorizes database operations into 'SAFE', 'DESTRUCTIVE', 'SCHEMA CHANGE', and 'TRANSACTION' tools, allowing for granular permission control in MCP clients, preventing unintended data modifications or schema changes by LLMs.

database llm-agents ai-ml

npm install mcp-sqlite-tools

package ↗

INSTALL

IMPORT

SIG · MCP-SQLITE-TOOLS

mcp-sqlite-tools

databasejavascriptv0.0.17

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MCPSQLiteServer

✓ import { MCPSQLiteServer } from 'mcp-sqlite-tools';

✗ const MCPSQLiteServer = require('mcp-sqlite-tools').MCPSQLiteServer;

Main class for instantiating and configuring the MCP SQLite server. Primarily designed for ESM environments, though CommonJS might be supported via transpilation or specific build targets. Using `require` for named exports is generally incorrect in pure CommonJS when the source is ESM.

MCPSQLiteServerOptions

✓ import type { MCPSQLiteServerOptions } from 'mcp-sqlite-tools';

TypeScript type for configuring the `MCPSQLiteServer` instance. Use `type` import for better bundle tree-shaking and to clearly distinguish from runtime values.

startMCPSQLiteServer

✓ import { startMCPSQLiteServer } from 'mcp-sqlite-tools';

A potential convenience function to quickly initialize and start the server without directly instantiating the class. Check documentation for its availability and specific usage.

This quickstart demonstrates how to instantiate and run the `mcp-sqlite-tools` server, configuring it to listen on a specific port and manage a local SQLite database within a restricted directory for security. It includes basic error handling and graceful shutdown.

import { MCPSQLiteServer } from 'mcp-sqlite-tools'; import path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); async function main() { const databasePath = path.join(__dirname, 'data', 'my-database.sqlite'); // Ensure the directory for the database exists const databaseDir = path.dirname(databasePath); await import('node:fs/promises').then(fs => fs.mkdir(databaseDir, { recursive: true })); const server = new MCPSQLiteServer({ port: 3000, databasePath: databasePath, // Restrict database operations to a specific directory for security allowedPaths: [path.join(__dirname, 'data')], // Enable verbose logging for debugging logLevel: 'debug', // Optional: Configure connection pool settings connectionPool: { max: 10, min: 2, idleTimeoutMillis: 30000 } }); try { await server.start(); console.log(`MCP SQLite Server listening on port 3000. Database: ${databasePath}`); // Example: Graceful shutdown on process termination process.on('SIGTERM', async () => { console.log('SIGTERM signal received. Shutting down server...'); await server.stop(); console.log('Server stopped.'); process.exit(0); }); process.on('SIGINT', async () => { console.log('SIGINT signal received. Shutting down server...'); await server.stop(); console.log('Server stopped.'); process.exit(0); }); } catch (error) { console.error('Failed to start MCP SQLite Server:', error); process.exit(1); } } main();

mcp-sqlite-tools --version

Debug

Known issues

breakingAs a pre-1.0 package (version 0.0.17), the API is subject to frequent and potentially breaking changes. Direct usage in production without pinning exact versions is discouraged, and migration efforts should be anticipated with minor version bumps.

fix

Pin exact versions (e.g., `"mcp-sqlite-tools": "0.0.17"`) in `package.json` and review changelogs carefully when upgrading.

affects: >=0.0.1

gotchaThe server's security features, including `allowedPaths` and query classification, are critical. Misconfiguration of `allowedPaths` can prevent the server from accessing intended database files or, conversely, expose it to unintended file system access outside of sandboxed directories. Incorrect client-side approval logic for 'DESTRUCTIVE' or 'SCHEMA CHANGE' tools can lead to unauthorized modifications.

fix

Carefully define `allowedPaths` to include only necessary directories. Implement robust client-side approval flows as suggested in the README for 'DESTRUCTIVE' and 'SCHEMA CHANGE' tools to prevent accidental or malicious actions by LLMs.

affects: >=0.0.1

gotchaThis package is an MCP *server*. It exposes an API for MCP clients (like LLMs) to interact with SQLite. It does not provide client-side utilities for directly calling database operations from your Node.js application. Your application interacts with the server, which then handles the SQLite logic.

fix

Understand that this package is the backend for database operations. If you need direct Node.js SQLite access within your application, consider using libraries like `sqlite3` or `better-sqlite3` directly, or interact with this server via its defined MCP interface.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'sqlite3' (or 'better-sqlite3')

The `mcp-sqlite-tools` server relies on an underlying SQLite driver, but one is not installed or discoverable in the project's dependencies.

fix

Install a compatible SQLite driver: `npm install sqlite3` or `npm install better-sqlite3`. Ensure native dependencies are correctly built, especially on different operating systems or Node.js versions.

Error: Path validation failed. The provided path is not within the allowed directories.

The `databasePath` or a path referenced in a query falls outside the `allowedPaths` configured in the `MCPSQLiteServerOptions`, a security measure to prevent directory traversal.

fix

Verify that `databasePath` and any paths used within queries are correctly configured and explicitly listed in the `allowedPaths` array when instantiating `MCPSQLiteServer`.

TypeError: Cannot read properties of undefined (reading 'start')

The `MCPSQLiteServer` class or `startMCPSQLiteServer` function was not correctly imported, or the instance was not properly created before attempting to call methods on it.

fix

Ensure `import { MCPSQLiteServer } from 'mcp-sqlite-tools';` is present and that you are instantiating the server correctly with `new MCPSQLiteServer(...)` before calling `.start()`.

Upgrade

Version history

0.0.17latest on npm

Audit

Dependencies

sqlite3optionalRuntime dependency for interacting with SQLite databases. While the server abstracts the driver, a compatible SQLite binding (like `sqlite3` or `better-sqlite3`) must be available in the environment.

better-sqlite3optionalAlternative runtime dependency for interacting with SQLite databases, often preferred for synchronous operations and performance. Similar to `sqlite3`, a binding must be available.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/mcp-sqlite-tools ↗