MCP SQLite Tools Server

Common errors

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

  cause 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.

  cause 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')

  cause 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()`.

Warnings

• breaking As 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.
• gotcha The 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.
• gotcha This 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.

Install

• npm install mcp-sqlite-tools npm
• yarn add mcp-sqlite-tools yarn
• pnpm add mcp-sqlite-tools pnpm

Imports

• MCPSQLiteServer
  wrong:

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

  correct:

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

  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.

Quickstart

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();