{"id":51414063,"url":"https://github.com/spences10/mcp-sqlite-tools","last_synced_at":"2026-07-04T17:30:39.374Z","repository":{"id":306898569,"uuid":"1027594373","full_name":"spences10/mcp-sqlite-tools","owner":"spences10","description":"A Model Context Protocol (MCP) server that provides comprehensive SQLite database operations for LLMs. This server enables AI assistants to interact with local SQLite databases safely and efficiently, with built-in security features, advanced transaction support, and clear separation between read-only and destructive operations.","archived":false,"fork":false,"pushed_at":"2026-07-01T21:23:23.000Z","size":395,"stargazers_count":19,"open_issues_count":2,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T23:22:12.877Z","etag":null,"topics":["mcp","sqlite"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spences10.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-28T08:44:31.000Z","updated_at":"2026-07-01T21:21:54.000Z","dependencies_parsed_at":"2025-07-28T10:31:01.592Z","dependency_job_id":"087a1ea1-98d2-4ccd-b5b9-100b64bfc99b","html_url":"https://github.com/spences10/mcp-sqlite-tools","commit_stats":null,"previous_names":["spences10/mcp-sqlite-tools"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/spences10/mcp-sqlite-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spences10%2Fmcp-sqlite-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spences10%2Fmcp-sqlite-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spences10%2Fmcp-sqlite-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spences10%2Fmcp-sqlite-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spences10","download_url":"https://codeload.github.com/spences10/mcp-sqlite-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spences10%2Fmcp-sqlite-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35130722,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","sqlite"],"created_at":"2026-07-04T17:30:38.592Z","updated_at":"2026-07-04T17:30:39.364Z","avatar_url":"https://github.com/spences10.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-sqlite-tools\n\nA Model Context Protocol (MCP) server that provides comprehensive\nSQLite database operations for LLMs. This server enables AI assistants\nto interact with local SQLite databases safely and efficiently, with\nbuilt-in security features, advanced transaction support, and clear\nseparation between read-only and destructive operations.\n\n## Features\n\n### 🗄️ Database Management\n\n- **Open/Create Database**: Open existing databases or create new ones\n- **Close Database**: Properly close database connections\n- **List Databases**: Discover database files in directories\n- **Database Info**: Get comprehensive database metadata and\n  statistics\n\n### 📊 Table Operations\n\n- **List Tables**: View all tables and views in a database\n- **Describe Table**: Get detailed schema information for tables\n- **Create Table**: Create new tables with custom column definitions\n- **Drop Table**: Remove tables (with safety warnings)\n\n### 🔍 Query Operations\n\n- **Execute Read Query**: Safe SELECT, PRAGMA, and EXPLAIN queries\n- **Execute Write Query**: INSERT, UPDATE, DELETE operations\n- **Execute Schema Query**: DDL operations (CREATE, ALTER, DROP)\n- **Bulk Insert**: Efficient batch insertion of multiple records\n\n### 💾 Transaction Management\n\n- **Begin Transaction**: Start database transactions with savepoint\n  support\n- **Commit Transaction**: Commit changes with nested transaction\n  handling\n- **Rollback Transaction**: Safely rollback changes and nested\n  savepoints\n- **Auto-cleanup**: Automatic cleanup of stale transactions\n\n### 📋 Schema Operations\n\n- **Export Schema**: Export database schema to SQL or JSON format\n- **Import Schema**: Import and execute schema from SQL or JSON\n- **Selective Export**: Export specific tables or entire database\n  structure\n\n### 🛠️ Database Maintenance\n\n- **Backup Database**: Create database backups with timestamps\n- **Vacuum Database**: Optimize database storage and performance\n- **Connection Pooling**: Advanced connection management with health\n  monitoring\n\n## ⚠️ Security Features\n\nThis server implements multiple layers of security:\n\n- **Query Classification**: Automatic separation of read-only, write,\n  schema, and transaction operations\n- **Path Validation**: Prevents directory traversal attacks\n- **Configurable Path Restrictions**: Control access to absolute paths\n- **Input Validation**: Comprehensive parameter validation using\n  Valibot\n- **Advanced Connection Pooling**: Connection limits, health\n  monitoring, and idle timeout\n- **Transaction Safety**: Automatic stale transaction cleanup and\n  nested savepoint support\n- **Resource Cleanup**: Graceful cleanup on server shutdown with\n  maintenance scheduling\n\n### Tool Separation for Hook-Based Safety\n\nThe tools are intentionally separated into distinct categories to\nenable fine-grained approval control in MCP clients like Claude Code:\n\n**✓ SAFE Tools** (Read-only operations):\n\n- `execute_read_query` - SELECT, PRAGMA, EXPLAIN queries\n- `list_tables`, `describe_table`, `database_info`\n- `export_schema`, `backup_database`\n\nThese tools can be auto-approved or approved once, allowing the AI to\nfreely explore your database structure and read data.\n\n**⚠️ DESTRUCTIVE Tools** (Data modification):\n\n- `execute_write_query` - INSERT, UPDATE, DELETE\n- `bulk_insert` - Batch insertions\n- `import_csv` - CSV data import\n- `drop_table` - Permanent table deletion\n\nThese tools should require individual approval for each operation,\ngiving you visibility into what data will be modified before it\nhappens.\n\n**⚠️ SCHEMA CHANGE Tools** (Structure modification):\n\n- `execute_schema_query` - CREATE, ALTER, DROP statements\n- `create_table` - Table creation\n- `import_schema` - Schema import\n- `import_csv` - Can create missing tables from CSV headers\n\nThese tools modify database structure and should require individual\napproval to prevent unintended schema changes.\n\n**⚠️ FILE WRITE Tools**:\n\n- `export_csv` - Writes CSV files, including absolute paths\n\n**🔒 TRANSACTION Tools**:\n\n- `begin_transaction`, `commit_transaction`, `rollback_transaction`\n\nCan be configured based on your workflow needs.\n\n**Example Claude Code Hook Configuration:**\n\n```javascript\n// In your Claude Code hooks\nexport function toolApproval(tool) {\n\t// Auto-approve safe read operations\n\tif (\n\t\ttool.name.includes('read') ||\n\t\ttool.name.includes('list') ||\n\t\ttool.name.includes('describe') ||\n\t\ttool.name.includes('export') ||\n\t\ttool.name.includes('backup') ||\n\t\ttool.name.includes('info')\n\t) {\n\t\treturn 'auto-approve';\n\t}\n\n\t// Require approval for destructive operations\n\tif (\n\t\ttool.name.includes('write') ||\n\t\ttool.name.includes('delete') ||\n\t\ttool.name.includes('drop') ||\n\t\ttool.name.includes('insert') ||\n\t\ttool.name.includes('schema')\n\t) {\n\t\treturn 'require-approval';\n\t}\n\n\treturn 'require-approval'; // Default to safe\n}\n```\n\nThis separation ensures you maintain control over destructive\noperations while allowing the AI to work efficiently with read-only\nqueries.\n\n## Installation\n\n### From npm (when published)\n\n```bash\nnpm install -g mcp-sqlite-tools\n```\n\n### From source\n\n```bash\ngit clone \u003crepository-url\u003e\ncd mcp-sqlite-tools\npnpm install\npnpm run build\n```\n\n## Configuration\n\n### Environment Variables\n\nThe server can be configured using environment variables:\n\n```bash\n# Default directory for SQLite databases (relative to project root)\nSQLITE_DEFAULT_PATH=.\n\n# Allow absolute paths for database files (security setting)\nSQLITE_ALLOW_ABSOLUTE_PATHS=true\n\n# SQLite lock busy timeout in milliseconds (not wall-clock query runtime)\nSQLITE_BUSY_TIMEOUT=30000\n\n# Default backup directory for database backups\nSQLITE_BACKUP_PATH=./backups\n\n# Enable debug logging\nDEBUG=false\n```\n\n### MCP Client Configuration\n\n#### Option 1: Global User Configuration (Recommended)\n\nConfigure once in your VS Code user settings to work across all\nworkspaces. Add this to your global `mcp.json` file\n(`%APPDATA%\\Code\\User\\mcp.json` on Windows):\n\nFor VS Code global configuration, edit `~/.config/Code/User/mcp.json`\n(or equivalent Windows location):\n\n```json\n{\n\t\"servers\": {\n\t\t\"sqlite-tools\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"mcp-sqlite-tools\"]\n\t\t}\n\t}\n}\n```\n\n**For WSL users**, use this format in your global config:\n\n```json\n{\n\t\"servers\": {\n\t\t\"sqlite-tools\": {\n\t\t\t\"command\": \"wsl.exe\",\n\t\t\t\"args\": [\"bash\", \"-c\", \"npx -y mcp-sqlite-tools\"]\n\t\t}\n\t}\n}\n```\n\n**Benefits:**\n\n- ✅ **One configuration works everywhere** - no per-project setup\n  needed\n- 📁 **Automatically uses current workspace** - databases created in\n  whatever project you have open\n- 🔄 **Always up to date** - uses latest published version via npx\n\n#### Option 2: Workspace-Specific Configuration\n\nFor teams that want to share database configuration via version\ncontrol, create a `.vscode/mcp.json` file in your workspace:\n\n```json\n{\n\t\"servers\": {\n\t\t\"sqlite-tools\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"mcp-sqlite-tools\"],\n\t\t\t\"env\": {\n\t\t\t\t\"SQLITE_DEFAULT_PATH\": \"${workspaceFolder}/databases\",\n\t\t\t\t\"SQLITE_ALLOW_ABSOLUTE_PATHS\": \"true\",\n\t\t\t\t\"SQLITE_BACKUP_PATH\": \"${workspaceFolder}/backups\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n**Benefits:**\n\n- � **Team sharing** - configuration committed to version control\n- 📂 **Organized structure** - databases in dedicated `/databases`\n  folder\n- �️ **Project isolation** - each project has its own database\n  configuration\n\n#### Claude Desktop / Cline Configuration\n\nAdd this to your MCP client configuration:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"mcp-sqlite-tools\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"mcp-sqlite-tools\"],\n\t\t\t\"env\": {\n\t\t\t\t\"SQLITE_DEFAULT_PATH\": \".\",\n\t\t\t\t\"SQLITE_ALLOW_ABSOLUTE_PATHS\": \"true\",\n\t\t\t\t\"SQLITE_BUSY_TIMEOUT\": \"30000\",\n\t\t\t\t\"SQLITE_BACKUP_PATH\": \"./backups\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### Environment Variables\n\nThe following environment variables can be used to configure the MCP\nserver:\n\n| Variable                      | Description                                 | Default                       | Example                        |\n| ----------------------------- | ------------------------------------------- | ----------------------------- | ------------------------------ |\n| `SQLITE_DEFAULT_PATH`         | Default directory for database files        | `.`                           | `${workspaceFolder}/databases` |\n| `SQLITE_ALLOW_ABSOLUTE_PATHS` | Allow absolute paths in database operations | `true`                        | `false`                        |\n| `SQLITE_BACKUP_PATH`          | Default directory for database backups      | Same as `SQLITE_DEFAULT_PATH` | `./backups`                    |\n| `SQLITE_BUSY_TIMEOUT`         | SQLite lock busy timeout in milliseconds    | `30000`                       | `60000`                        |\n\n`SQLITE_MAX_QUERY_TIME` is still accepted as a deprecated alias for\n`SQLITE_BUSY_TIMEOUT`; it is not a wall-clock query runtime limit.\n\n**Path Resolution:**\n\n- Relative paths are resolved from the default path\n- Use `${workspaceFolder}` in VS Code for workspace-relative paths\n- Set `SQLITE_ALLOW_ABSOLUTE_PATHS=true` to enable absolute path\n  operations\n\n#### Development Configuration\n\nFor development with the MCP inspector:\n\n```bash\npnpm run build\npnpm run dev\n```\n\n## API Reference\n\n### Database Management Tools\n\n#### `open_database`\n\nOpens or creates a SQLite database file.\n\n**Parameters:**\n\n- `path` (string, required): Path to the database file\n- `create` (boolean, optional): Create if doesn't exist (default:\n  true)\n\n**Example:**\n\n```json\n{\n\t\"path\": \"my-app.db\",\n\t\"create\": true\n}\n```\n\n#### `close_database`\n\nCloses a database connection.\n\n**Parameters:**\n\n- `database` (string, optional): Database path to close\n\n#### `list_databases`\n\nLists available database files in a directory.\n\n**Parameters:**\n\n- `directory` (string, optional): Directory to search\n\n#### `database_info`\n\nGets comprehensive information about a database.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n### Table Operations\n\n#### `list_tables`\n\nLists all tables and views in a database.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n#### `describe_table`\n\nGets schema information for a table.\n\n**Parameters:**\n\n- `table` (string, required): Table name\n- `database` (string, optional): Database path\n- `verbosity` (string, optional): 'summary' or 'detailed' (default:\n  'detailed')\n\n**Example Request:**\n\n```json\n{\n\t\"table\": \"users\",\n\t\"verbosity\": \"detailed\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n\t\"database\": \"/tmp/demo.db\",\n\t\"table\": \"users\",\n\t\"columns\": [\n\t\t{\n\t\t\t\"name\": \"id\",\n\t\t\t\"type\": \"INTEGER\",\n\t\t\t\"nullable\": true,\n\t\t\t\"default_value\": null,\n\t\t\t\"primary_key\": true\n\t\t},\n\t\t{\n\t\t\t\"name\": \"name\",\n\t\t\t\"type\": \"TEXT\",\n\t\t\t\"nullable\": false,\n\t\t\t\"default_value\": null,\n\t\t\t\"primary_key\": false\n\t\t},\n\t\t{\n\t\t\t\"name\": \"email\",\n\t\t\t\"type\": \"TEXT\",\n\t\t\t\"nullable\": true,\n\t\t\t\"default_value\": null,\n\t\t\t\"primary_key\": false\n\t\t},\n\t\t{\n\t\t\t\"name\": \"created_at\",\n\t\t\t\"type\": \"TIMESTAMP\",\n\t\t\t\"nullable\": true,\n\t\t\t\"default_value\": \"CURRENT_TIMESTAMP\",\n\t\t\t\"primary_key\": false\n\t\t}\n\t],\n\t\"verbosity\": \"detailed\",\n\t\"column_count\": 4\n}\n```\n\n#### `create_table`\n\nCreates a new table with specified columns.\n\n**Parameters:**\n\n- `name` (string, required): Table name\n- `columns` (array, required): Column definitions\n- `database` (string, optional): Database path\n\n**Column Definition:**\n\n```json\n{\n\t\"name\": \"column_name\",\n\t\"type\": \"TEXT|INTEGER|REAL|BLOB\",\n\t\"nullable\": true,\n\t\"primary_key\": false,\n\t\"default_value\": null\n}\n```\n\n**Example:**\n\n```json\n{\n\t\"name\": \"users\",\n\t\"columns\": [\n\t\t{\n\t\t\t\"name\": \"id\",\n\t\t\t\"type\": \"INTEGER\",\n\t\t\t\"primary_key\": true,\n\t\t\t\"nullable\": false\n\t\t},\n\t\t{\n\t\t\t\"name\": \"name\",\n\t\t\t\"type\": \"TEXT\",\n\t\t\t\"nullable\": false\n\t\t},\n\t\t{\n\t\t\t\"name\": \"email\",\n\t\t\t\"type\": \"TEXT\",\n\t\t\t\"nullable\": true\n\t\t}\n\t]\n}\n```\n\n#### `drop_table`\n\nPermanently deletes a table and all its data.\n\n**Parameters:**\n\n- `table` (string, required): Table name to delete\n- `database` (string, optional): Database path\n\n### Query Operations\n\n#### `execute_read_query`\n\nExecutes read-only SQL queries (SELECT, PRAGMA, EXPLAIN).\n\n**Parameters:**\n\n- `query` (string, required): SQL query\n- `params` (object, optional): Query parameters\n- `database` (string, optional): Database path\n- `limit` (number, optional): Maximum rows to return (default: 10000)\n- `offset` (number, optional): Number of rows to skip (default: 0)\n- `verbosity` (string, optional): 'summary' or 'detailed' (default:\n  'detailed')\n\n**Example Request:**\n\n```json\n{\n\t\"query\": \"SELECT * FROM users ORDER BY id\",\n\t\"verbosity\": \"detailed\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n\t\"database\": \"/tmp/demo.db\",\n\t\"query\": \"SELECT * FROM users ORDER BY id LIMIT 10000\",\n\t\"result\": {\n\t\t\"rows\": [\n\t\t\t{\n\t\t\t\t\"id\": 1,\n\t\t\t\t\"name\": \"Alice Johnson\",\n\t\t\t\t\"email\": \"alice@example.com\",\n\t\t\t\t\"created_at\": \"2025-10-03 09:42:04\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"id\": 3,\n\t\t\t\t\"name\": \"Carol White\",\n\t\t\t\t\"email\": \"carol@example.com\",\n\t\t\t\t\"created_at\": \"2025-10-03 09:42:10\"\n\t\t\t}\n\t\t],\n\t\t\"changes\": 0,\n\t\t\"last_insert_rowid\": 0\n\t},\n\t\"row_count\": 2,\n\t\"pagination\": {\n\t\t\"limit\": 10000,\n\t\t\"offset\": 0,\n\t\t\"returned_count\": 2,\n\t\t\"has_more\": false\n\t},\n\t\"verbosity\": \"detailed\"\n}\n```\n\n#### `execute_write_query`\n\nExecutes SQL that modifies data (INSERT, UPDATE, DELETE).\n\n**Parameters:**\n\n- `query` (string, required): SQL query\n- `params` (object, optional): Query parameters\n- `database` (string, optional): Database path\n\n**Example Request:**\n\n```json\n{\n\t\"query\": \"INSERT INTO users (name, email) VALUES ('Alice Smith', 'alice@example.com')\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n\t\"database\": \"/tmp/demo.db\",\n\t\"query\": \"INSERT INTO users (name, email) VALUES ('Alice Smith', 'alice@example.com')\",\n\t\"result\": {\n\t\t\"rows\": [],\n\t\t\"changes\": 1,\n\t\t\"last_insert_rowid\": 1\n\t},\n\t\"message\": \"⚠️ DESTRUCTIVE OPERATION COMPLETED: Data modified in database '/tmp/demo.db'. Rows affected: 1\"\n}\n```\n\n#### `execute_schema_query`\n\nExecutes DDL queries (CREATE, ALTER, DROP).\n\n**Parameters:**\n\n- `query` (string, required): DDL SQL query\n- `params` (object, optional): Query parameters\n- `database` (string, optional): Database path\n\n**Example Request:**\n\n```json\n{\n\t\"query\": \"CREATE TABLE users (\\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\\n  name TEXT NOT NULL,\\n  email TEXT UNIQUE,\\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\\n)\"\n}\n```\n\n**Example Response:**\n\n```json\n{\n\t\"database\": \"/tmp/demo.db\",\n\t\"query\": \"CREATE TABLE users (\\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\\n  name TEXT NOT NULL,\\n  email TEXT UNIQUE,\\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\\n)\",\n\t\"result\": {\n\t\t\"rows\": [],\n\t\t\"changes\": 0,\n\t\t\"last_insert_rowid\": 0\n\t},\n\t\"message\": \"⚠️ SCHEMA CHANGE COMPLETED: Database structure modified in '/tmp/demo.db'. Changes: 0\"\n}\n```\n\n#### `bulk_insert`\n\nInsert multiple records in batches.\n\n**Parameters:**\n\n- `table` (string, required): Target table name\n- `data` (array, required): Array of objects to insert\n- `batch_size` (number, optional): Records per batch (default: 1000)\n- `database` (string, optional): Database path\n\n**Example Request:**\n\n```json\n{\n\t\"table\": \"users\",\n\t\"data\": [\n\t\t{ \"name\": \"David Lee\", \"email\": \"david@example.com\" },\n\t\t{ \"name\": \"Emma Davis\", \"email\": \"emma@example.com\" },\n\t\t{ \"name\": \"Frank Miller\", \"email\": \"frank@example.com\" }\n\t]\n}\n```\n\n**Example Response:**\n\n```json\n{\n\t\"success\": true,\n\t\"database\": \"/tmp/demo.db\",\n\t\"table\": \"users\",\n\t\"inserted\": 3,\n\t\"batches\": 1,\n\t\"total_time\": 0,\n\t\"message\": \"⚠️ DESTRUCTIVE OPERATION COMPLETED: 3 records inserted into table 'users' in database '/tmp/demo.db'\"\n}\n```\n\n### CSV Operations\n\n#### `import_csv`\n\nImport a headered CSV file into a table. If the table does not exist,\nit is created from CSV headers with inferred SQLite column types.\nValues are coerced by default (`\"\"`/`null` to NULL, numbers to\nnumbers, booleans to 1/0). Row-level insert errors are reported and\nsuccessful rows continue unless `fail_fast` is true.\n\n**Parameters:**\n\n- `table` (string, required): Target table name\n- `file_path` (string, required): CSV file path; absolute paths\n  allowed\n- `database_name` (string, optional): Database path or current context\n  name\n- `create_table` (boolean, optional): Create missing table (default:\n  true)\n- `batch_size` (number, optional): Rows per batch (default: 1000)\n- `fail_fast` (boolean, optional): Stop on first row error (default:\n  false)\n- `max_errors` (number, optional): Max row errors returned\n  (default: 100)\n- `coerce_types` (boolean, optional): Coerce CSV strings (default:\n  true)\n- `delimiter`, `quote`, `escape`, `encoding` (optional): CSV parsing\n  options\n\n#### `export_csv`\n\nExport either a full table or a read-only query result to CSV. Provide\nexactly one of `table` or `query`.\n\n**Parameters:**\n\n- `file_path` (string, required): Output CSV path; absolute paths\n  allowed\n- `table` (string, optional): Table to export\n- `query` (string, optional): Read-only query to export\n- `database_name` (string, optional): Database path or current context\n  name\n- `delimiter`, `record_delimiter`, `encoding` (optional): CSV output\n  options\n- `always_quote` (boolean, optional): Quote every field (default:\n  false)\n- `append` (boolean, optional): Append to existing file (default:\n  false)\n\n### Transaction Management\n\n#### `begin_transaction`\n\nStart a database transaction with optional savepoint support.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n**Returns:** Transaction ID for tracking\n\n#### `commit_transaction`\n\nCommit the current transaction or release a savepoint.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n#### `rollback_transaction`\n\nRollback the current transaction or revert to a savepoint.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n### Schema Operations\n\n#### `export_schema`\n\nExport database schema to SQL or JSON format.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n- `format` (string, optional): Output format - \"sql\" or \"json\"\n  (default: \"sql\")\n- `tables` (array, optional): Specific tables to export\n\n**Example:**\n\n```json\n{\n\t\"format\": \"json\",\n\t\"tables\": [\"users\", \"orders\"]\n}\n```\n\n#### `import_schema`\n\nImport and execute schema from SQL or JSON.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n- `schema` (string, required): Schema content to import\n- `format` (string, optional): Input format - \"sql\" or \"json\"\n  (default: \"sql\")\n\n### Database Maintenance\n\n#### `backup_database`\n\nCreates a consistent SQLite backup using SQLite's online backup API,\nincluding committed data that may still be in WAL files.\n\n**Parameters:**\n\n- `source_database` (string, optional): Source database path\n- `backup_path` (string, optional): Backup file path (auto-generated\n  if not provided)\n\n#### `vacuum_database`\n\nOptimizes database storage by reclaiming unused space.\n\n**Parameters:**\n\n- `database` (string, optional): Database path\n\n## Safety Guidelines\n\n### Tool Classification\n\nThe server automatically classifies tools into safety categories:\n\n1. **✓ SAFE**: Read-only operations (SELECT, PRAGMA, EXPLAIN, database\n   info, backups)\n2. **⚠️ DESTRUCTIVE**: Data modification (INSERT, UPDATE, DELETE, bulk\n   insert, CSV import)\n3. **⚠️ SCHEMA CHANGE**: Structure modification (CREATE, ALTER, DROP,\n   schema import, CSV table creation)\n4. **⚠️ FILE WRITE**: Export operations that write files, including\n   absolute CSV paths\n5. **⚠️ TRANSACTION**: Transaction control (BEGIN, COMMIT, ROLLBACK)\n6. **✓ MAINTENANCE**: Optimization operations (VACUUM, connection\n   management)\n\n### Best Practices\n\n1. **Always use parameterized queries** to prevent SQL injection\n2. **Use transactions** for multi-step operations to ensure data\n   consistency\n3. **Review destructive operations** before execution\n4. **Create backups** before major schema changes\n5. **Use bulk_insert** for inserting large datasets efficiently\n6. **Review CSV absolute paths** before import/export file operations\n7. **Export schemas** before major structural changes\n8. **Use appropriate tools** for different operation types\n9. **Monitor connection pool** usage in high-traffic scenarios\n\n## Development\n\n### Building\n\n```bash\npnpm run build\n```\n\n### Development Mode\n\n```bash\npnpm run dev\n```\n\n### Cleaning\n\n```bash\npnpm run clean\n```\n\n## Architecture\n\nThe server is built with a modular architecture:\n\n### Core Modules\n\n- **`src/index.ts`**: Main server entry point\n- **`src/config.ts`**: Configuration management with Valibot\n  validation\n\n### Database Clients\n\n- **`src/clients/connection-manager.ts`**: Advanced connection pooling\n  with health monitoring\n- **`src/clients/query-executor.ts`**: SQL execution, bulk operations,\n  and query utilities\n- **`src/clients/transaction-manager.ts`**: ACID transaction\n  management with savepoints\n- **`src/clients/schema-manager.ts`**: Schema export/import\n  functionality\n- **`src/clients/sqlite.ts`**: Main SQLite client interface and\n  utilities\n\n### Tool Handlers\n\n- **`src/tools/handler.ts`**: Tool registration orchestrator\n- **`src/tools/admin-tools.ts`**: Database and table management tools\n- **`src/tools/query-tools.ts`**: Query execution and bulk operation\n  tools\n- **`src/tools/transaction-tools.ts`**: Transaction management tools\n- **`src/tools/schema-tools.ts`**: Schema export/import tools\n- **`src/tools/csv-tools.ts`**: CSV import/export tools\n- **`src/tools/context.ts`**: Database context management\n\n### Common Utilities\n\n- **`src/common/types.ts`**: TypeScript type definitions\n- **`src/common/errors.ts`**: Error handling utilities\n- **`src/common/sql.ts`**: SQL identifier and literal helpers\n- **`src/common/schema-sql.ts`**: SQLite schema statement parsing\n\nThis modular design provides:\n\n- **Separation of Concerns**: Each module has a single responsibility\n- **Maintainability**: Easy to test, debug, and extend individual\n  components\n- **Scalability**: New features can be added without affecting\n  existing code\n- **Type Safety**: Comprehensive TypeScript coverage throughout\n\n## Dependencies\n\n- **[tmcp](https://github.com/paoloricciuti/tmcp)**: Modern TypeScript\n  MCP framework\n- **[better-sqlite3](https://github.com/WiseLibs/better-sqlite3)**:\n  High-performance SQLite driver\n- **[valibot](https://valibot.dev/)**: Lightweight validation library\n  for type-safe inputs\n- **[csv-parser](https://github.com/mafintosh/csv-parser)**: CSV\n  import parsing\n- **[csv-writer](https://github.com/ryu1kn/csv-writer)**: CSV export\n  writing\n\n### Key Features Provided by Dependencies\n\n- **tmcp**: Streamlined MCP server development with excellent\n  TypeScript support\n- **better-sqlite3**: Synchronous SQLite operations with superior\n  performance\n- **valibot**: Runtime type validation for all tool parameters\n- **csv-\\***: Headered CSV import/export with type coercion and\n  row-level import error reporting\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built on the\n  [Model Context Protocol](https://github.com/modelcontextprotocol)\n- Inspired by\n  [mcp-turso-cloud](https://github.com/spences10/mcp-turso-cloud)\n- Uses [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)\n  for high-performance SQLite operations\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspences10%2Fmcp-sqlite-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspences10%2Fmcp-sqlite-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspences10%2Fmcp-sqlite-tools/lists"}