mcp-sqlite-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofer Shapira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# mcp-server-sqlite
+
+[![npm version](https://img.shields.io/npm/v/mcp-sqlite-server.svg)](https://www.npmjs.com/package/mcp-sqlite-server)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-sqlite-server.svg)](https://www.npmjs.com/package/mcp-sqlite-server)
+[![CI](https://github.com/ofershap/mcp-server-sqlite/actions/workflows/ci.yml/badge.svg)](https://github.com/ofershap/mcp-server-sqlite/actions/workflows/ci.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Query SQLite databases, inspect schemas, and explain queries from your AI assistant. Read-only by default for safety.
+
+```bash
+npx mcp-sqlite-server
+```
+
+> Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Reads local `.db` files, no auth needed.
+
+![MCP server for querying SQLite databases and inspecting schemas](assets/demo.gif)
+
+<sub>Demo built with <a href="https://github.com/ofershap/remotion-readme-kit">remotion-readme-kit</a></sub>
+
+## Why
+
+SQLite is everywhere. It's the default database for mobile apps, Electron apps, local-first tools, and increasingly for server-side projects too (Turso, Cloudflare D1, Bun's built-in SQLite). The official MCP reference includes a basic SQLite server, but it's Python-only. If you're working in a TypeScript/Node.js environment and want to ask your assistant "what tables are in this database?" or "run this query and show me the results," this server handles that. It opens the database read-only by default so you can explore safely, and you can opt into write mode when you need it.
+
+## Tools
+
+| Tool             | What it does                                                             |
+| ---------------- | ------------------------------------------------------------------------ |
+| `query`          | Execute SQL (SELECT, PRAGMA, EXPLAIN, WITH). Returns results as a table. |
+| `schema`         | Get full schema: all tables with columns, types, and row counts.         |
+| `table_info`     | Detailed info for a single table: columns, constraints, row count.       |
+| `explain`        | Run EXPLAIN QUERY PLAN to optimize queries.                              |
+| `list_databases` | List .db, .sqlite, .sqlite3 files in a directory.                        |
+
+## Quick Start
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": ["mcp-sqlite-server"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "npx",
+      "args": ["mcp-sqlite-server"]
+    }
+  }
+}
+```
+
+### VS Code
+
+Configure the MCP server in your VS Code settings to run `npx mcp-sqlite-server`.
+
+## Example prompts
+
+- "Show me the schema of my database at ./data.db"
+- "Query the users table: SELECT * FROM users LIMIT 10"
+- "Explain the query plan for this complex join"
+- "What tables are in this database?"
+- "Find all .db files in the current directory"
+
+## Safety
+
+Read-only by default. The `query` tool accepts only SELECT, PRAGMA, EXPLAIN, and WITH in readonly mode. Set `readonly=false` in the tool args to enable INSERT, UPDATE, DELETE, etc.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+npm run format
+npm run lint
+```
+
+## Author
+
+**Ofer Shapira**
+
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-ofershap-blue?logo=linkedin)](https://linkedin.com/in/ofershap)
+[![GitHub](https://img.shields.io/badge/GitHub-ofershap-black?logo=github)](https://github.com/ofershap)
+
+## License
+
+MIT © 2026 Ofer Shapira

package/dist/index.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import path2 from "path";
+import { z } from "zod";
+
+// src/sqlite.ts
+import Database from "better-sqlite3";
+import fs from "fs";
+import path from "path";
+function openDb(dbPath) {
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Database file not found: ${dbPath}`);
+  }
+  return new Database(dbPath, { readonly: true });
+}
+function openDbWritable(dbPath) {
+  return new Database(dbPath);
+}
+function query(dbPath, sql, readonly = true) {
+  const db = readonly ? openDb(dbPath) : openDbWritable(dbPath);
+  try {
+    const trimmed = sql.trim();
+    const isSelect = /^(SELECT|PRAGMA|EXPLAIN|WITH)\b/i.test(trimmed);
+    if (readonly && !isSelect) {
+      throw new Error(
+        "Write operations are not allowed in read-only mode. Set readonly=false to enable writes."
+      );
+    }
+    if (isSelect) {
+      const stmt = db.prepare(trimmed);
+      const rows = stmt.all();
+      const firstRow = rows[0];
+      const columns = firstRow ? Object.keys(firstRow) : [];
+      return { columns, rows, rowCount: rows.length };
+    } else {
+      db.exec(trimmed);
+      return { columns: [], rows: [], rowCount: 0 };
+    }
+  } finally {
+    db.close();
+  }
+}
+function schema(dbPath) {
+  const db = openDb(dbPath);
+  try {
+    const tables = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    ).all();
+    const tableInfos = tables.map((t) => {
+      const columns = db.prepare(`PRAGMA table_info("${t.name}")`).all();
+      const countResult = db.prepare(`SELECT COUNT(*) as count FROM "${t.name}"`).get();
+      return {
+        name: t.name,
+        columns: columns.map((c) => ({
+          name: c.name,
+          type: c.type,
+          notnull: c.notnull === 1,
+          pk: c.pk === 1,
+          defaultValue: c.dflt_value
+        })),
+        rowCount: countResult.count
+      };
+    });
+    return { tables: tableInfos, totalTables: tableInfos.length };
+  } finally {
+    db.close();
+  }
+}
+function tableInfo(dbPath, tableName) {
+  const db = openDb(dbPath);
+  try {
+    const columns = db.prepare(`PRAGMA table_info("${tableName}")`).all();
+    if (columns.length === 0) {
+      throw new Error(`Table "${tableName}" not found`);
+    }
+    const countResult = db.prepare(`SELECT COUNT(*) as count FROM "${tableName}"`).get();
+    return {
+      name: tableName,
+      columns: columns.map((c) => ({
+        name: c.name,
+        type: c.type,
+        notnull: c.notnull === 1,
+        pk: c.pk === 1,
+        defaultValue: c.dflt_value
+      })),
+      rowCount: countResult.count
+    };
+  } finally {
+    db.close();
+  }
+}
+function explain(dbPath, sql) {
+  const db = openDb(dbPath);
+  try {
+    const rows = db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all();
+    return rows.map((r) => `${r.id} | ${r.parent} | ${r.detail}`).join("\n");
+  } finally {
+    db.close();
+  }
+}
+function listDatabases(directory) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  return entries.filter((e) => e.isFile() && /\.(db|sqlite|sqlite3)$/i.test(e.name)).map((e) => path.join(directory, e.name)).sort();
+}
+
+// src/index.ts
+function formatQueryResult(columns, rows) {
+  if (columns.length === 0 && rows.length === 0) {
+    return "(No columns returned)";
+  }
+  if (columns.length === 0) {
+    return `(${rows.length} row(s) affected)`;
+  }
+  const widths = columns.map(
+    (col) => Math.max(col.length, ...rows.map((r) => String(r[col] ?? "").length))
+  );
+  const sep = widths.map((w) => "-".repeat(w)).join("-+-");
+  const header = columns.map((c, i) => c.padEnd(widths[i] ?? 0)).join(" | ");
+  const lines = [header, sep];
+  for (const row of rows) {
+    const line = columns.map((c, i) => String(row[c] ?? "").padEnd(widths[i] ?? 0)).join(" | ");
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function formatSchema(schemaInfo) {
+  const lines = [`Schema: ${schemaInfo.totalTables} table(s)`, ""];
+  for (const t of schemaInfo.tables) {
+    const colSpecs = t.columns.map((c) => {
+      let spec = `${c.name} (${c.type})`;
+      if (c.pk) spec += " PK";
+      if (c.notnull) spec += " NOT NULL";
+      if (c.defaultValue != null) spec += ` DEFAULT ${c.defaultValue}`;
+      return spec;
+    });
+    lines.push(`### ${t.name} (${t.rowCount} rows)`);
+    lines.push(colSpecs.map((s) => `  - ${s}`).join("\n"));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+var server = new McpServer({
+  name: "mcp-server-sqlite",
+  version: "1.0.0"
+});
+server.tool(
+  "query",
+  "Execute a SQL query against a SQLite database. Returns results as a formatted table. Read-only by default.",
+  {
+    db: z.string().describe("Path to the .db or .sqlite file"),
+    sql: z.string().describe("SQL query to execute"),
+    readonly: z.boolean().default(true).describe("If true, only SELECT/PRAGMA/EXPLAIN allowed")
+  },
+  async ({ db, sql, readonly }) => {
+    try {
+      const resolved = path2.resolve(db);
+      const result = query(resolved, sql, readonly);
+      const text = formatQueryResult(result.columns, result.rows);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Rows: ${result.rowCount}
+
+${text}`
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "schema",
+  "Get the schema of a SQLite database: all tables with columns and row counts.",
+  {
+    db: z.string().describe("Path to the .db or .sqlite file")
+  },
+  async ({ db }) => {
+    try {
+      const resolved = path2.resolve(db);
+      const schemaInfo = schema(resolved);
+      const text = formatSchema(schemaInfo);
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "table_info",
+  "Get detailed info about a single table: columns, types, constraints, and row count.",
+  {
+    db: z.string().describe("Path to the .db or .sqlite file"),
+    table: z.string().describe("Table name")
+  },
+  async ({ db, table }) => {
+    try {
+      const resolved = path2.resolve(db);
+      const info = tableInfo(resolved, table);
+      const colSpecs = info.columns.map((c) => {
+        let spec = `${c.name} (${c.type})`;
+        if (c.pk) spec += " PK";
+        if (c.notnull) spec += " NOT NULL";
+        if (c.defaultValue != null) spec += ` DEFAULT ${c.defaultValue}`;
+        return spec;
+      });
+      const text = [
+        `### ${info.name} (${info.rowCount} rows)`,
+        "",
+        ...colSpecs.map((s) => `- ${s}`)
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "explain",
+  "Explain the query plan for a SQL query (EXPLAIN QUERY PLAN). Helps optimize queries.",
+  {
+    db: z.string().describe("Path to the .db or .sqlite file"),
+    sql: z.string().describe("SQL query to explain")
+  },
+  async ({ db, sql }) => {
+    try {
+      const resolved = path2.resolve(db);
+      const plan = explain(resolved, sql);
+      return {
+        content: [{ type: "text", text: `Query plan:
+${plan}` }]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "list_databases",
+  "List all SQLite database files (.db, .sqlite, .sqlite3) in a directory.",
+  {
+    directory: z.string().default(".").describe("Directory path to scan (default: current directory)")
+  },
+  async ({ directory }) => {
+    try {
+      const resolved = path2.resolve(directory);
+      const dbs = listDatabases(resolved);
+      if (dbs.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No .db, .sqlite, or .sqlite3 files found in ${resolved}`
+            }
+          ]
+        };
+      }
+      const text = dbs.map((p) => `- ${p}`).join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${dbs.length} database(s):
+
+${text}`
+          }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sqlite.ts"],"sourcesContent":["import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport path from \"node:path\";\nimport { z } from \"zod\";\nimport type { TableInfo } from \"./sqlite.js\";\nimport { query, schema, tableInfo, explain, listDatabases } from \"./sqlite.js\";\n\nfunction formatQueryResult(\n  columns: string[],\n  rows: Record<string, unknown>[],\n): string {\n  if (columns.length === 0 && rows.length === 0) {\n    return \"(No columns returned)\";\n  }\n  if (columns.length === 0) {\n    return `(${rows.length} row(s) affected)`;\n  }\n  const widths = columns.map((col) =>\n    Math.max(col.length, ...rows.map((r) => String(r[col] ?? \"\").length)),\n  );\n  const sep = widths.map((w) => \"-\".repeat(w)).join(\"-+-\");\n  const header = columns.map((c, i) => c.padEnd(widths[i] ?? 0)).join(\" | \");\n  const lines = [header, sep];\n  for (const row of rows) {\n    const line = columns\n      .map((c, i) => String(row[c] ?? \"\").padEnd(widths[i] ?? 0))\n      .join(\" | \");\n    lines.push(line);\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction formatSchema(schemaInfo: {\n  tables: {\n    name: string;\n    columns: {\n      name: string;\n      type: string;\n      notnull: boolean;\n      pk: boolean;\n      defaultValue: string | null;\n    }[];\n    rowCount: number;\n  }[];\n  totalTables: number;\n}): string {\n  const lines: string[] = [`Schema: ${schemaInfo.totalTables} table(s)`, \"\"];\n  for (const t of schemaInfo.tables) {\n    const colSpecs = t.columns.map((c) => {\n      let spec = `${c.name} (${c.type})`;\n      if (c.pk) spec += \" PK\";\n      if (c.notnull) spec += \" NOT NULL\";\n      if (c.defaultValue != null) spec += ` DEFAULT ${c.defaultValue}`;\n      return spec;\n    });\n    lines.push(`### ${t.name} (${t.rowCount} rows)`);\n    lines.push(colSpecs.map((s) => `  - ${s}`).join(\"\\n\"));\n    lines.push(\"\");\n  }\n  return lines.join(\"\\n\").trimEnd();\n}\n\nconst server = new McpServer({\n  name: \"mcp-server-sqlite\",\n  version: \"1.0.0\",\n});\n\nserver.tool(\n  \"query\",\n  \"Execute a SQL query against a SQLite database. Returns results as a formatted table. Read-only by default.\",\n  {\n    db: z.string().describe(\"Path to the .db or .sqlite file\"),\n    sql: z.string().describe(\"SQL query to execute\"),\n    readonly: z\n      .boolean()\n      .default(true)\n      .describe(\"If true, only SELECT/PRAGMA/EXPLAIN allowed\"),\n  },\n  async ({ db, sql, readonly }) => {\n    try {\n      const resolved = path.resolve(db);\n      const result = query(resolved, sql, readonly);\n      const text = formatQueryResult(result.columns, result.rows);\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Rows: ${result.rowCount}\\n\\n${text}`,\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"schema\",\n  \"Get the schema of a SQLite database: all tables with columns and row counts.\",\n  {\n    db: z.string().describe(\"Path to the .db or .sqlite file\"),\n  },\n  async ({ db }) => {\n    try {\n      const resolved = path.resolve(db);\n      const schemaInfo = schema(resolved);\n      const text = formatSchema(schemaInfo);\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"table_info\",\n  \"Get detailed info about a single table: columns, types, constraints, and row count.\",\n  {\n    db: z.string().describe(\"Path to the .db or .sqlite file\"),\n    table: z.string().describe(\"Table name\"),\n  },\n  async ({ db, table }) => {\n    try {\n      const resolved = path.resolve(db);\n      const info = tableInfo(resolved, table);\n      const colSpecs = info.columns.map((c: TableInfo[\"columns\"][number]) => {\n        let spec = `${c.name} (${c.type})`;\n        if (c.pk) spec += \" PK\";\n        if (c.notnull) spec += \" NOT NULL\";\n        if (c.defaultValue != null) spec += ` DEFAULT ${c.defaultValue}`;\n        return spec;\n      });\n      const text = [\n        `### ${info.name} (${info.rowCount} rows)`,\n        \"\",\n        ...colSpecs.map((s: string) => `- ${s}`),\n      ].join(\"\\n\");\n      return { content: [{ type: \"text\", text }] };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"explain\",\n  \"Explain the query plan for a SQL query (EXPLAIN QUERY PLAN). Helps optimize queries.\",\n  {\n    db: z.string().describe(\"Path to the .db or .sqlite file\"),\n    sql: z.string().describe(\"SQL query to explain\"),\n  },\n  async ({ db, sql }) => {\n    try {\n      const resolved = path.resolve(db);\n      const plan = explain(resolved, sql);\n      return {\n        content: [{ type: \"text\", text: `Query plan:\\n${plan}` }],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nserver.tool(\n  \"list_databases\",\n  \"List all SQLite database files (.db, .sqlite, .sqlite3) in a directory.\",\n  {\n    directory: z\n      .string()\n      .default(\".\")\n      .describe(\"Directory path to scan (default: current directory)\"),\n  },\n  async ({ directory }) => {\n    try {\n      const resolved = path.resolve(directory);\n      const dbs = listDatabases(resolved);\n      if (dbs.length === 0) {\n        return {\n          content: [\n            {\n              type: \"text\",\n              text: `No .db, .sqlite, or .sqlite3 files found in ${resolved}`,\n            },\n          ],\n        };\n      }\n      const text = dbs.map((p: string) => `- ${p}`).join(\"\\n\");\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Found ${dbs.length} database(s):\\n\\n${text}`,\n          },\n        ],\n      };\n    } catch (err) {\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: `Error: ${err instanceof Error ? err.message : String(err)}`,\n          },\n        ],\n        isError: true,\n      };\n    }\n  },\n);\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((err) => {\n  console.error(\"Fatal error:\", err);\n  process.exit(1);\n});\n","import Database from \"better-sqlite3\";\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\nexport interface QueryResult {\n  columns: string[];\n  rows: Record<string, unknown>[];\n  rowCount: number;\n}\n\nexport interface TableInfo {\n  name: string;\n  columns: {\n    name: string;\n    type: string;\n    notnull: boolean;\n    pk: boolean;\n    defaultValue: string | null;\n  }[];\n  rowCount: number;\n}\n\nexport interface SchemaInfo {\n  tables: TableInfo[];\n  totalTables: number;\n}\n\nfunction openDb(dbPath: string): Database.Database {\n  if (!fs.existsSync(dbPath)) {\n    throw new Error(`Database file not found: ${dbPath}`);\n  }\n  return new Database(dbPath, { readonly: true });\n}\n\nfunction openDbWritable(dbPath: string): Database.Database {\n  return new Database(dbPath);\n}\n\nexport function query(\n  dbPath: string,\n  sql: string,\n  readonly = true,\n): QueryResult {\n  const db = readonly ? openDb(dbPath) : openDbWritable(dbPath);\n  try {\n    const trimmed = sql.trim();\n    const isSelect = /^(SELECT|PRAGMA|EXPLAIN|WITH)\\b/i.test(trimmed);\n\n    if (readonly && !isSelect) {\n      throw new Error(\n        \"Write operations are not allowed in read-only mode. Set readonly=false to enable writes.\",\n      );\n    }\n\n    if (isSelect) {\n      const stmt = db.prepare(trimmed);\n      const rows = stmt.all() as Record<string, unknown>[];\n      const firstRow = rows[0];\n      const columns = firstRow ? Object.keys(firstRow) : [];\n      return { columns, rows, rowCount: rows.length };\n    } else {\n      db.exec(trimmed);\n      return { columns: [], rows: [], rowCount: 0 };\n    }\n  } finally {\n    db.close();\n  }\n}\n\nexport function schema(dbPath: string): SchemaInfo {\n  const db = openDb(dbPath);\n  try {\n    const tables = db\n      .prepare(\n        \"SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name\",\n      )\n      .all() as { name: string }[];\n\n    const tableInfos: TableInfo[] = tables.map((t) => {\n      const columns = db.prepare(`PRAGMA table_info(\"${t.name}\")`).all() as {\n        name: string;\n        type: string;\n        notnull: number;\n        pk: number;\n        dflt_value: string | null;\n      }[];\n\n      const countResult = db\n        .prepare(`SELECT COUNT(*) as count FROM \"${t.name}\"`)\n        .get() as { count: number };\n\n      return {\n        name: t.name,\n        columns: columns.map((c) => ({\n          name: c.name,\n          type: c.type,\n          notnull: c.notnull === 1,\n          pk: c.pk === 1,\n          defaultValue: c.dflt_value,\n        })),\n        rowCount: countResult.count,\n      };\n    });\n\n    return { tables: tableInfos, totalTables: tableInfos.length };\n  } finally {\n    db.close();\n  }\n}\n\nexport function tableInfo(dbPath: string, tableName: string): TableInfo {\n  const db = openDb(dbPath);\n  try {\n    const columns = db.prepare(`PRAGMA table_info(\"${tableName}\")`).all() as {\n      name: string;\n      type: string;\n      notnull: number;\n      pk: number;\n      dflt_value: string | null;\n    }[];\n    if (columns.length === 0) {\n      throw new Error(`Table \"${tableName}\" not found`);\n    }\n\n    const countResult = db\n      .prepare(`SELECT COUNT(*) as count FROM \"${tableName}\"`)\n      .get() as { count: number };\n\n    return {\n      name: tableName,\n      columns: columns.map((c) => ({\n        name: c.name,\n        type: c.type,\n        notnull: c.notnull === 1,\n        pk: c.pk === 1,\n        defaultValue: c.dflt_value,\n      })),\n      rowCount: countResult.count,\n    };\n  } finally {\n    db.close();\n  }\n}\n\nexport function explain(dbPath: string, sql: string): string {\n  const db = openDb(dbPath);\n  try {\n    const rows = db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all() as Record<\n      string,\n      unknown\n    >[];\n    return rows.map((r) => `${r.id} | ${r.parent} | ${r.detail}`).join(\"\\n\");\n  } finally {\n    db.close();\n  }\n}\n\nexport function listDatabases(directory: string): string[] {\n  const entries = fs.readdirSync(directory, { withFileTypes: true });\n  return entries\n    .filter((e) => e.isFile() && /\\.(db|sqlite|sqlite3)$/i.test(e.name))\n    .map((e) => path.join(directory, e.name))\n    .sort();\n}\n"],"mappings":"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","names":["path","path"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "mcp-sqlite-server",
+  "version": "1.0.0",
+  "description": "MCP server for SQLite — query databases, inspect schemas, explain queries, and export data from your IDE",
+  "type": "module",
+  "bin": {
+    "mcp-sqlite-server": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "sqlite",
+    "database",
+    "sql",
+    "query",
+    "schema",
+    "turso",
+    "d1",
+    "ai",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "author": "Ofer Shapira",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ofershap/mcp-server-sqlite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ofershap/mcp-server-sqlite/issues"
+  },
+  "homepage": "https://github.com/ofershap/mcp-server-sqlite#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^11.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "husky": "^9.0.0",
+    "lint-staged": "^15.0.0",
+    "prettier": "^3.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.0"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js}": "eslint --fix",
+    "*.{json,md,yml,yaml}": "prettier --write"
+  }
+}