Claude Code 接入 SQLite 全流程

在使用 Claude Code 或其他 AI 智能助手辅助开发和数据分析时，我们常常希望它能够 直接从数据库获取数据，而不是手动把 SQL 查询结果复制粘贴给它。为了解决这个问题，可以用 MCP（Model Context Protocol）协议构建一个桥接服务，让 AI 能直接操作本地数据库，实现自动化数据查询、结构获取及结果返回。本文将带你完整从零构建一个 MCP Server，让 Claude Code 直接操控 SQLite 数据库。

在这个过程中，你甚至可以将 MCP 与 koalaapi此类辅助开发平台整合起来，实现更自动化的数据调度与 API 管理。

---

一、MCP Server 是什么？

在默认情况下，像 Claude Code、GPT Agent 等 AI 模型 无法直接访问本地文件、数据库或 API。MCP（Model Context Protocol）就是一套中间协议，它定义了 AI 和本地工具之间的通信格式，通过 JSON‑RPC 消息让 AI 调用你定义的“工具”。Server 接收到调用后执行代码，并把执行结果返回给 AI。

信息流大致如下：

Claude Code ──(MCP协议)──> MCP Server ──(SQL/工具调用)──> SQLite 数据库

这样，AI 不再依赖手工复制 SQL 结果，而可以直接“看见”数据库中的结构和数据。

---

二、项目初始化

1）创建项目并安装依赖

首先创建工程目录并引入必要依赖：

mkdir my-sqlite-mcp && cd my-sqlite-mcp
npm init -y
npm install @modelcontextprotocol/sdk better-sqlite3
npm install -D typescript @types/node @types/better-sqlite3

接着初始化 TypeScript（创建 tsconfig.json）：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

在 package.json 中新增构建与启动脚本：

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

上述依赖准备好后，我们就可以开始写 MCP Server 主体了。

---

三、构建 Server 主体

在 src/index.ts 中写入以下代码：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import Database from "better-sqlite3";
import { z } from "zod";
import path from "path";

// 从命令行参数获取数据库路径
const dbPath = process.argv[2];
if (!dbPath) {
  console.error("Usage: node dist/index.js <database file path>");
  process.exit(1);
}

// 打开 SQLite 数据库
const db = new Database(path.resolve(dbPath), { readonly: false });
db.pragma("journal_mode = WAL"); // 提升并发性能

const server = new McpServer({
  name: "sqlite-mcp",
  version: "1.0.0",
});

这部分逻辑做了三件事：

1. 从命令行获取 SQLite 文件路径
2. 用 better-sqlite3 同步方式打开数据库
3. 初始化 MCP Server 实例

MCP Server 会监听标准输入输出，通过 JSON‑RPC 和 Claude Code 进行通信。

---

四、注册核心工具（Tools）

MCP Server 的核心就是“工具（Tool）”定义——这些工具可以被 Claude Code 调用。

1）列出所有数据库表

server.tool(
  "list_tables",
  "列出所有表和视图",
  {},
  async () => {
    const tables = db.prepare(
      "SELECT name, type FROM sqlite_master WHERE type IN ('table','view') ORDER BY name"
    ).all();
    return {
      content: [{
        type: "text",
        text: JSON.stringify(tables, null, 2)
      }]
    };
  }
);

返回的数据是包含所有表名和类型的 JSON，对应 SQLite 内部的 sqlite_master 表。

---

2）查看表结构

server.tool(
  "describe_table",
  "查看指定表的字段结构",
  { table_name: z.string().describe("表名") },
  async ({ table_name }) => {
    if (!/^[\w]+$/.test(table_name)) {
      return { content: [{ type: "text", text: "错误：表名包含非法字符" }], isError: true };
    }
    const columns = db.prepare(`PRAGMA table_info("${table_name}")`).all();
    if (columns.length === 0) {
      return { content: [{ type: "text", text: `表 ${table_name} 不存在` }], isError: true };
    }
    return { content: [{ type: "text", text: JSON.stringify(columns, null, 2) }] };
  }
);

这个工具会返回表的所有字段信息，包括字段名、类型、是否主键等。

---

3）执行 SQL 查询

server.tool(
  "query",
  "执行 SQL 查询（只允许 SELECT）",
  {
    sql: z.string().describe("SQL 字符串"),
    limit: z.number().optional().default(100).describe("最大返回行数")
  },
  async ({ sql, limit }) => {
    const trimmed = sql.trim().toUpperCase();
    if (!trimmed.startsWith("SELECT") && !trimmed.startsWith("WITH")) {
      return {
        content: [{ type: "text", text: "只允许 SELECT 查询。写入请用 execute 工具。" }],
        isError: true
      };
    }
    try {
      const stmt = db.prepare(sql);
      const rows = stmt.all().slice(0, limit);
      return {
        content: [{ type: "text", text: `查询返回 ${rows.length} 行:\n${JSON.stringify(rows, null, 2)}` }]
      };
    } catch (e: any) {
      return { content: [{ type: "text", text: `SQL 错误: ${e.message}` }], isError: true };
    }
  }
);

默认最多返回 100 行，避免结果过大导致上下文拥堵。

---

五、写入操作

如果你信任 AI 自动执行写入语句，还可以注册一个 execute 工具：

server.tool(
  "execute",
  "执行写入 SQL（INSERT/UPDATE/DELETE 等）",
  { sql: z.string().describe("写入 SQL") },
  async ({ sql }) => {
    try {
      const result = db.prepare(sql).run();
      return {
        content: [{ type: "text", text: `执行完成，影响行数：${result.changes}` }]
      };
    } catch (e: any) {
      return { content: [{ type: "text", text: `SQL 错误: ${e.message}` }], isError: true };
    }
  }
);

虽然写入工具很强大，但在生产环境建议谨慎启用。

---

六、启动 MCP Server 并与 Claude Code 连接

在文件末尾加入启动逻辑：

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("sqlite-mcp 已启动，数据库:", dbPath);
}

main().catch((e) => {
  console.error("启动失败:", e);
  process.exit(1);
});

注意 使用 console.error 输出日志，因为 MCP 协议占用 stdout 进行数据传输，日志必须走 stderr，否则会破坏协议流。 然后：

npm run build
node dist/index.js ./test.db

如果看到错误输出“sqlite‑mcp 已启动”，说明服务已经就绪。

---

七、在 Claude Code 中使用

创建配置文件 .mcp.json：

{
  "mcpServers": {
    "sqlite": {
      "command": "node",
      "args": [
        "/绝对路径/my-sqlite-mcp/dist/index.js",
        "/绝对路径/database.db"
      ]
    }
  }
}

重启 Claude Code 后，它就能自动识别 MCP Server 和定义的工具了。

接下来你可以直接跟 Claude Code 说：

帮我查一下 users 表有多少条记录

Claude 就会调用你注册的 query 工具执行查询并返回结构化结果。

---

八、真实使用场景与踩坑总结

作者分享了自己的实践经验：

📌 场景 1：数据排查 通过自然语言问题让 Claude 自动执行多个 SQL 查询和分析，大大提高效率。

📌 场景 2：数据迁移脚本生成 AI 自动创建迁移语句、执行并验证结果，一气呵成。

📌 场景 3：自动报表 在短时间内生成多表聚合报表。

常见坑点：

✔ .mcp.json 中数据库路径请使用绝对路径 ✔ 默认 limit 设置为 100 行避免过大返回 ✔ 日志必须输出到 stderr，否则 MCP 协议流会出错

---

结语

本文通过完整步骤教你从零构建一套 MCP Server，使 Claude Code 能直接操作 SQLite 数据库。不仅学会了核心实现，还了解了与 AI 交互的实用模式。