{"id":16647,"library":"mcp-sqlite-tools","title":"MCP SQLite Tools Server","description":"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.","status":"active","version":"0.0.17","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","mcp","model-context-protocol","sqlite","database","sql","llm","ai","local-database","typescript"],"install":[{"cmd":"npm install mcp-sqlite-tools","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-sqlite-tools","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-sqlite-tools","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime 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.","package":"sqlite3","optional":true},{"reason":"Alternative runtime dependency for interacting with SQLite databases, often preferred for synchronous operations and performance. Similar to `sqlite3`, a binding must be available.","package":"better-sqlite3","optional":true}],"imports":[{"note":"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.","wrong":"const MCPSQLiteServer = require('mcp-sqlite-tools').MCPSQLiteServer;","symbol":"MCPSQLiteServer","correct":"import { MCPSQLiteServer } from 'mcp-sqlite-tools';"},{"note":"TypeScript type for configuring the `MCPSQLiteServer` instance. Use `type` import for better bundle tree-shaking and to clearly distinguish from runtime values.","symbol":"MCPSQLiteServerOptions","correct":"import type { MCPSQLiteServerOptions } from 'mcp-sqlite-tools';"},{"note":"A potential convenience function to quickly initialize and start the server without directly instantiating the class. Check documentation for its availability and specific usage.","symbol":"startMCPSQLiteServer","correct":"import { startMCPSQLiteServer } from 'mcp-sqlite-tools';"}],"quickstart":{"code":"import { MCPSQLiteServer } from 'mcp-sqlite-tools';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nasync function main() {\n  const databasePath = path.join(__dirname, 'data', 'my-database.sqlite');\n\n  // Ensure the directory for the database exists\n  const databaseDir = path.dirname(databasePath);\n  await import('node:fs/promises').then(fs => fs.mkdir(databaseDir, { recursive: true }));\n\n  const server = new MCPSQLiteServer({\n    port: 3000,\n    databasePath: databasePath,\n    // Restrict database operations to a specific directory for security\n    allowedPaths: [path.join(__dirname, 'data')],\n    // Enable verbose logging for debugging\n    logLevel: 'debug',\n    // Optional: Configure connection pool settings\n    connectionPool: {\n      max: 10,\n      min: 2,\n      idleTimeoutMillis: 30000\n    }\n  });\n\n  try {\n    await server.start();\n    console.log(`MCP SQLite Server listening on port 3000. Database: ${databasePath}`);\n\n    // Example: Graceful shutdown on process termination\n    process.on('SIGTERM', async () => {\n      console.log('SIGTERM signal received. Shutting down server...');\n      await server.stop();\n      console.log('Server stopped.');\n      process.exit(0);\n    });\n\n    process.on('SIGINT', async () => {\n      console.log('SIGINT signal received. Shutting down server...');\n      await server.stop();\n      console.log('Server stopped.');\n      process.exit(0);\n    });\n\n  } catch (error) {\n    console.error('Failed to start MCP SQLite Server:', error);\n    process.exit(1);\n  }\n}\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"fix":"Pin exact versions (e.g., `\"mcp-sqlite-tools\": \"0.0.17\"`) in `package.json` and review changelogs carefully when upgrading.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `mcp-sqlite-tools` server relies on an underlying SQLite driver, but one is not installed or discoverable in the project's dependencies.","error":"Error: Cannot find module 'sqlite3' (or 'better-sqlite3')"},{"fix":"Verify that `databasePath` and any paths used within queries are correctly configured and explicitly listed in the `allowedPaths` array when instantiating `MCPSQLiteServer`.","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.","error":"Error: Path validation failed. The provided path is not within the allowed directories."},{"fix":"Ensure `import { MCPSQLiteServer } from 'mcp-sqlite-tools';` is present and that you are instantiating the server correctly with `new MCPSQLiteServer(...)` before calling `.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.","error":"TypeError: Cannot read properties of undefined (reading 'start')"}],"ecosystem":"npm"}