sqlite-echarts-mcp

一个标准的 Model Context Protocol server：连接一个 SQLite 数据库，提供只读查询、库表结构浏览，以及「查询 → 可直接渲染的 ECharts option」能力，供任意支持 MCP 的客户端/大模型调用。

• 只读安全：只允许 SELECT / WITH / PRAGMA / EXPLAIN，SELECT 自动下推 LIMIT。
• 图表即用：line_chart / bar_chart / pie_chart / scatter_chart 直接返回完整 ECharts option，前端 echarts.setOption() 即可渲染，无需再做映射。
• 零原生依赖：基于 Node 内置的 node:sqlite，npx 安装无需编译。
• stdio 传输：标准 MCP 进程协议，可被 Claude / Cursor / 各类 Agent 框架接入。
• 双通道返回：content 给模型一段摘要，structuredContent 承载完整数据，避免大数据撑满上下文。

要求

| 项 | 说明 | | --- | --- | | Node.js | ≥ 22.5.0（需内置 node:sqlite） | | 数据库 | 一个已存在的 SQLite 文件（以只读方式打开） | | 网络 | 仅 npm install 时需访问 npm registry（拉取 @modelcontextprotocol/sdk） |

快速开始

# 1. 安装依赖
npm install

# 2. 直接运行（纯 JS，无需构建）
node index.js /abs/path/to/data.sqlite

数据库路径也可用环境变量指定：

SQLITE_DB=/abs/path/to/data.sqlite node index.js

启动后服务监听 stdio，日志只写 stderr（stdout 是 MCP 线协议）。

工具

query

只读执行 SQL。

• 入参：{ "sql": string }
• 允许：SELECT / WITH / PRAGMA / EXPLAIN；其余（INSERT/UPDATE/DELETE/CREATE/DROP/ALTER/…）被拒绝。
• 无 LIMIT 的 SELECT 自动追加 LIMIT 1000。

返回（双通道：content 给模型、structuredContent 给客户端）：

// content[0].text —— 摘要
"查询返回 2 行（列: date, total）\n[\"2026-08-01\",250]\n[\"2026-08-02\",280]"

// structuredContent —— 完整数据
{ "ok": true, "columns": ["date", "total"], "rows": [["2026-08-01", 250], ["2026-08-02", 280]], "rowCount": 2, "truncated": false }

schema

浏览库结构。

• 入参：{ "table"?: string }（可选）
• 不带 table → 列出所有表/视图：{ "ok": true, "tables": [{ "name": "sales", "type": "table" }] }
• 带 table → 返回该表字段（等价 PRAGMA table_info）：{ "ok": true, "columns": [{ "name": "amount", "type": "REAL", "notnull": 0, "dflt": null, "pk": 0 }] }

line_chart / bar_chart / scatter_chart

分别执行聚合 SQL 并返回可直接 echarts.setOption() 的完整 ECharts option（折线图 / 柱状图 / 散点图）。入参不再包含 chart.type：

{
  "sql": "SELECT date, sum(amount) AS total FROM sales GROUP BY date ORDER BY date",
  // 或 "data": [{ "date": "2026-08-01", "total": 250 }, ...]   // 二选一，data 跳过查询
  "xKey": "date",            // 必填：x 轴取值列
  "yKey": "total",           // 单序列：与 series 二选一
  "title": "每日销售",        // 可选
  "xLabel": "日期",           // 可选
  "yLabel": "金额"            // 可选
}

多序列：

{ "xKey": "date",
  "series": [ { "name": "东部", "key": "east" }, { "name": "西部", "key": "west" } ] }

pie_chart

执行聚合 SQL 并返回可直接 echarts.setOption() 的完整 ECharts 饼图 option。xKey 为标签列，yKey 为数值列：

{
  "sql": "SELECT region, sum(amount) AS total FROM sales GROUP BY region",
  // 或 "data": [{ "region": "华东", "total": 250 }, ...]
  "xKey": "region",
  "yKey": "total"
}

以上图表工具统一返回（双通道）：

// content[0].text —— 摘要，模型据此写分析
"已生成 line 图（3 行）\ntotal: 3 点，值域 [250, 290]，首=250，末=290"

// structuredContent —— 完整 option，客户端直接渲染
{ "ok": true, "rowCount": 3, "truncated": false,
  "option": {
    "title": { "text": "每日销售", "left": "center" },
    "tooltip": { "trigger": "axis" },
    "grid": { "left": 52, "right": 24, "top": 24, "bottom": 52 },
    "xAxis": { "type": "category", "data": ["2026-08-01", "2026-08-02", "2026-08-03"] },
    "yAxis": { "type": "value" },
    "series": [ { "name": "total", "type": "line", "sampling": "lttb",
                  "data": [ ["2026-08-01", 250], ["2026-08-02", 280], ["2026-08-03", 290] ] } ]
  } }

前端拿到后直接渲染：

const chart = echarts.init(el)
chart.setOption(result.structuredContent.option)   // result 为 MCP 的 CallToolResult

内置表现：折线/柱状/散点 > 60 个点时自动加 dataZoom（inside + slider）；折线启用 sampling:'lttb' 以承载大数据；饼图为环形图并带图例与百分比提示。

通过 npx 使用（发布后）

npx -y sqlite-echarts-mcp /abs/path/to/data.sqlite

在 MCP 客户端中注册

通用 mcpServers 配置（Claude / Cursor 等）

命令行参数形式：

{
  "mcpServers": {
    "sqlite-echarts": {
      "command": "npx",
      "args": ["-y", "sqlite-echarts-mcp", "/abs/path/to/data.sqlite"]
    }
  }
}

环境变量形式：

{
  "mcpServers": {
    "sqlite-echarts": {
      "command": "npx",
      "args": ["-y", "sqlite-echarts-mcp"],
      "env": { "SQLITE_DB": "/abs/path/to/data.sqlite" }
    }
  }
}

Claude Desktop

写入 claude_desktop_config.json：

{
  "mcpServers": {
    "sqlite-echarts": {
      "command": "npx",
      "args": ["-y", "sqlite-echarts-mcp", "/Users/me/data.sqlite"]
    }
  }
}

DeepSeek Harness（本仓库的 dsh-mcp-client）

在 profile 的 cordis.patch.yml 中插入：

- insert:
    - id: mcp-sqlite-echarts
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: sqlite
        transport: stdio
        command: node
        args: ['/abs/path/to/sqlite-echarts-mcp/index.js', '/abs/path/to/data.sqlite']

模型即可通过 mcp__sqlite__query / mcp__sqlite__schema / mcp__sqlite__line_chart / mcp__sqlite__bar_chart / mcp__sqlite__pie_chart / mcp__sqlite__scatter_chart 调用。

发布到 npm 供他人使用

npm login
npm publish

发布后任意机器执行：

npx -y sqlite-echarts-mcp /path/to/their.sqlite

package.json 的 files 字段只打包 index.js / db.js / chart.js / README.md。

安全性

• 数据库以 readOnly: true 打开（文件不存在报清晰错误，不隐式新建）。
• 工具层再叠加只读关键字白名单 + SELECT LIMIT 下推（默认 1000 行）。
• 密码/敏感信息无持久化；连接仅为本地/挂载文件路径。

开发与测试

项目为纯 ESM，无构建步骤。本地冒烟（可选，需自建样例库）：

# 用 node:sqlite 造一个样例库
node -e "const {DatabaseSync}=require('node:sqlite');const d=new DatabaseSync('/tmp/t.sqlite');d.exec('CREATE TABLE sales(date TEXT, region TEXT, amount REAL)');const i=d.prepare('INSERT INTO sales VALUES (?,?,?)');[['2026-08-01','east',100],['2026-08-02','west',160]].forEach(r=>i.run(...r));d.close()"

# 用 MCP Inspector 或任意客户端连接验证
npx @modelcontextprotocol/inspector node index.js /tmp/t.sqlite

限制

• 单实例连接单个 SQLite 文件；多库需启动多个实例。
• 图表工具的完整 option 走 structuredContent，模型上下文只进摘要；但若客户端把 structuredContent 也喂给模型，大图仍有 token 成本。
• SQLite 无 ClickHouse 式多 database 概念，schema 以「表/视图」为粒度。
• node:sqlite 在 Node 22.x 仍标记为实验性，运行时会打印一次 ExperimentalWarning，不影响使用。