tokenlite-mysql-mcp

TokenLite MySQL MCP

一个基于 Anthropic 的 Model Context Protocol（MCP） 实现的稳健、安全的 MySQL 数据库服务。
它专为解决当前通用 MCP 服务的不足而设计，具备优雅降级、主动性能保护和激进的令牌优化能力。

---

🌟 核心支柱

1. 安全查询优化器（AST 与 EXPLAIN）：通过预先分析查询来保护生产数据库。阻止超过可配置阈值的未使用索引全表扫描，并在 AST 层自动注入严格的 LIMIT 子句。
2. 基于 AST 的细粒度写入权限：默认情况下，TokenLite 为 100% 只读。你可以通过环境变量精准启用特定写入操作（INSERT、UPDATE、DELETE、DDL）。防火墙使用严格的 AST 解析来防止 SQL 注入和注释绕过攻击，并严格禁止权限提升命令（如 GRANT 或 CALL）。
3. 会话级纵深防御：如果服务配置为严格只读模式（所有写入变量均已禁用），TokenLite 会将 SET SESSION TRANSACTION READ ONLY 直接注入连接池套接字。这确保即使 AST 解析器理论上存在绕过漏洞，MySQL 引擎本身也会从物理层面拒绝任何数据修改。
4. 商业智能注入：连接原始数据与公司业务逻辑。探索数据库架构时会自动附加语义词典（metadata.json），并通过官方 MCP Prompts API（templates.json）提供语义模板，让大模型使用预先批准的分析查询，而不是凭空编造。
5. 基于图的语义架构：避免向大模型发送会占满上下文窗口的庞大架构。搜索表时，引擎会使用启发式方法推断隐式关系，并打包确切的“自动联接上下文”。
6. CSV 令牌压缩：数据库结果会高效转换为表格形式的 CSV Markdown，并以明确的方式表示 NULL（∅），与冗长的 JSON 相比，最多可节省 50% 的输出令牌数。当结果达到所应用的 LIMIT 时，会追加 -- rows: N (truncated at LIMIT X) 页脚，避免大模型误以为数据集完整。
7. MCP 补全：表名和模板关键词支持资源模板（mysql://tables/{name}）以及 query_templates 提示词的官方 completions/complete 能力。

---

📋 要求

• Node.js v20 或更高版本
• MySQL 5.7 或更高版本（建议使用 MySQL 8.0+）
• 具有 SELECT 和 SHOW VIEW 权限的 MySQL 用户。

---

🚀 安装与使用

你可以将此 MCP 服务与任何兼容的客户端搭配使用。以下是最受欢迎的几种客户端的配置方式。

1. Claude Desktop

编辑你的 claude_desktop_config.json（在 Windows 上通常位于 %APPDATA%\Claude\claude_desktop_config.json，在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json），并添加以下内容：

使用 NPX（推荐）

{
  "mcpServers": {
    "tokenlite-mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@andezdev/tokenlite-mysql-mcp"
      ],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "your_db_user",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "MCP_EXPLAIN_MAX_SCAN_ROWS": "1000",
        "MCP_QUERY_ROW_LIMIT": "500",
        "MCP_SAFE_QUERY_ENABLE_BLOCKING": "true"
      }
    }
  }
}

2. Claude Code（CLI）

你可以轻松地将此服务全局集成到 Claude Code 中：

claude mcp add tokenlite_mysql \
  -e DB_HOST="127.0.0.1" \
  -e DB_PORT="3306" \
  -e DB_USER="root" \
  -e DB_PASSWORD="your_password" \
  -e DB_NAME="your_database" \
  -- npx -y @andezdev/tokenlite-mysql-mcp

3. Cursor IDE

要在 Cursor IDE 中使用：

1. 打开 Cursor Settings > Features > MCP。
2. 点击 + Add New MCP Server。
3. 将 Type 设为 command。
4. 将其命名为 tokenlite-mysql。
5. 将命令设为：

   npx -y @andezdev/tokenlite-mysql-mcp
   

（注意：Cursor 会直接在 IDE 界面中处理环境变量，请确保在那里添加数据库凭据。）

---

⚙️ 环境变量参考

了解查询限制（两个独立参数）

execute_safe_query 会应用两个独立的限制。请勿混淆：

变量	控制内容	默认值	示例
MCP_EXPLAIN_MAX_SCAN_ROWS	安全门禁：如果 EXPLAIN 计划显示全表扫描（type: ALL）的估算行数超过此阈值，则阻止查询。查询会在执行之前被拒绝。	1000	5000 允许在没有索引的情况下扫描最多约 5000 行的表
MCP_QUERY_ROW_LIMIT	结果上限：返回给 LLM 的最大行数。在 AST 层注入 LIMIT。达到上限时，CSV 会包含 -- rows: N (truncated at LIMIT X)。	500	1000 每次 SELECT 最多返回 1000 行

已弃用的别名： MCP_SAFE_QUERY_MAX_ROWS 仍可作为 MCP_EXPLAIN_MAX_SCAN_ROWS 的回退值使用。它不控制结果 LIMIT。

示例：在 customers 表（约 1502 行）上使用 MCP_EXPLAIN_MAX_SCAN_ROWS=5000 和 MCP_QUERY_ROW_LIMIT=500：

1. SELECT * FROM customers → EXPLAIN 检查通过（1502 < 5000），执行时应用 LIMIT 500，返回 500 行 + 截断说明。
2. 配置相同，但表有 8000 行 → 在执行前被 EXPLAIN 阻止。

变量	描述	默认值	必填
DB_HOST	MySQL 主机地址	localhost	否
DB_PORT	MySQL 端口	3306	否
DB_USER	MySQL 用户名	root	否
DB_PASSWORD	MySQL 密码	''	否
DB_NAME	MySQL 数据库名称	test	是
MCP_EXPLAIN_MAX_SCAN_ROWS	EXPLAIN 护栏：阻止无索引全表扫描前允许的最大估算行数。	1000	否
MCP_QUERY_ROW_LIMIT	每次 SELECT 返回的最大行数（由 AST 注入 LIMIT + 截断说明）。	500	否
MCP_SAFE_QUERY_ENABLE_BLOCKING	启用或禁用 EXPLAIN 护栏。	true	否
MCP_METADATA_PATH	自定义 metadata.json 字典的绝对路径。	（已禁用）	否
MCP_TEMPLATES_PATH	自定义 templates.json 查询的绝对路径。	（已禁用）	否
TOOL_PREFIX	工具名称前缀（在运行多个实例时很有用）。	从 DB_NAME 推导（例如 mydb_）。仅当未设置 DB_NAME 时才使用随机回退值。	否
MCP_RATE_LIMIT_RPM	每分钟最多调用工具的次数（滑动窗口）。设为 0 可禁用。	60	否
MYSQL_QUERY_TIMEOUT	查询的最长执行时间（毫秒）。中止耗时过长的查询，以防止 DoS。	15000	否
MYSQL_CONNECTION_LIMIT	连接池的最大并发连接数。	10	否
MYSQL_CONNECT_TIMEOUT	等待套接字建立连接的最长时间（毫秒）。	10000	否
MYSQL_RETRY_ATTEMPTS	遇到暂时性连接错误（ECONNREFUSED、PROTOCOL_CONNECTION_LOST 等）时的最大重试次数。	3	否
MYSQL_RETRY_DELAY_MS	重试之间指数退避的基础延迟（毫秒）（1 秒、2 秒、4 秒……）。	1000	否
MYSQL_QUEUE_LIMIT	所有连接池连接均繁忙时，最多排队的请求数。防止 MySQL 宕机时队列无限增长。	50	否
MCP_DDL_CACHE_TTL	缓存 DDL 语句的生存时间（秒）。减少重复调用 search_schema 时的延迟。由 refresh_schema 使缓存失效。	60	否
MCP_LOG_LEVEL	MCP 日志通知的最低严重级别：debug、info、notice、warning、error、critical、alert、emergency。	info	否
ALLOW_INSERT_OPERATION	启用 INSERT 和 REPLACE 查询。	false	否
ALLOW_UPDATE_OPERATION	启用 UPDATE 查询。	false	否
ALLOW_DELETE_OPERATION	启用 DELETE 和 TRUNCATE 查询。	false	否
ALLOW_DDL_OPERATION	启用数据定义语言操作（CREATE、ALTER、DROP、RENAME）。	false	否
DB_SSL	为 MySQL 连接启用 TLS（建议用于托管数据库或云数据库）。	false	否
DB_SSL_REJECT_UNAUTHORIZED	当 DB_SSL=true 时，拒绝自签名或不受信任的 TLS 证书。	true	否

---

🛡️ 商业智能功能（选择启用）

TokenLite 可以让大模型了解贵公司的业务规则。要启用此功能，请通过 .env 或 MCP 客户端配置映射两个 JSON 文件的绝对路径：

metadata.json（语义字典）

翻译整数状态或内部术语，让大模型理解数据。

{
  "orders.status": {
    "pending": "The order is waiting for payment validation",
    "shipped": "The order has left the warehouse"
  }
}

自定义关系

定义启发式引擎无法自动检测的 FK 映射（例如，created_by → users）。在 metadata.json 中添加 _relationships 键：

{
  "orders.status": { "pending": "...", "shipped": "..." },
  "_relationships": {
    "orders.created_by": "users.id",
    "categories.parent_id": "categories.id"
  }
}

这些映射将被视为权威配置（而非启发式结果），并优先于自动检测。

启发式引擎还会根据名称匹配（+40）、数据类型验证（+30）、主键验证（+20）和索引是否存在（+10），为每个推断出的 FK 赋予一个置信度分数（0–100）。仅接受得分 ≥70 的 FK。

templates.json（预先审核的 SQL）

提供经过审核的模板，避免大模型对复杂指标产生幻觉。

[
  {
    "name": "Customer Lifetime Value (LTV)",
    "description": "Calculates total revenue generated by delivered orders per customer.",
    "sql": "SELECT c.id, SUM(oi.price) FROM customers c JOIN orders o... WHERE o.status='delivered'"
  }
]

---

📈 基准测试与 Token 节省

TokenLite 内置自动化基准测试套件，使用 o200k_base 分词（GPT-4o/GPT-5 标准）衡量效率提升。Token 数量为近似值——Claude 4.x 使用专有分词器，实际数量可能略有不同。

要在自己的环境中运行基准测试：

npm run benchmark

基线：标准 MCP 模式

基准测试与通用 MySQL MCP 服务使用的标准模式进行比较：将完整架构作为格式化 JSON 暴露为 information_schema.columns，并将查询结果作为 JSON.stringify(rows, null, 2) 返回，同时附带执行时间元数据。

1. 架构发现（输入 Token）

标准 MCP 服务会将整个架构倾倒给大模型。对于大型数据库，这会在每轮对话中消耗数千个输入 Token。TokenLite 的关系图会提供局部的自动联接上下文（目标表 + 直接父表 + 直接子表）。

场景	标准 MCP 模式	TokenLite	📉 节省
模拟数据（50 张表，企业 CRM）	15,566 tokens	883 tokens	94.3%
实测（9 张表，测试数据库）	2,208 tokens	531 tokens	75.9%

节省幅度会随表数量增加而提升：数据库中的表越多，节省越明显，因为标准模式会倾倒所有表，而 TokenLite 只会获取目标表及其 1 跳关系。

2. 查询结果载荷（输出 Token）

TokenLite 会将原始数据库行转换为紧凑、结构化的 CSV 格式。这可避免 JSON 语法开销（括号、花括号、重复键），并压缩返回给大模型的输出载荷。当行数达到服务器注入的 LIMIT 时，结果会附带截断页脚（例如 -- rows: 500 (truncated at LIMIT 500)），以便 Agent 知道可能还有更多数据。

模拟数据（包含多种情况：NULL、长描述、长度不一的内容）：

返回行数	标准 MCP 模式（Token）	TokenLite CSV（Token）	📉 输出节省（%）
10 行	1,167	601	48.5%
50 行	5,803	2,927	49.6%
100 行	11,607	5,842	49.7%
500 行	57,990	29,119	49.8%

实测数据（真实 MySQL 测试数据库，包含 NULL、ENUM 和长度可变的文本）：

返回行数	标准 MCP 模式（Token）	TokenLite CSV（Token）	📉 输出节省（%）
10 行	1,007	628	37.6%
50 行	5,029	3,114	38.1%
100 行	10,071	6,232	38.1%
500 行	50,327	31,116	38.2%

---

📊 日志记录与可观测性

TokenLite 使用 MCP 原生日志记录，通过 notifications/message 而非原始 stderr 输出。支持 MCP 日志记录的客户端（例如 MCP Inspector）会收到包含严重性级别、日志记录器名称和 JSON 数据的结构化日志消息。

严重性级别（从低到高）：debug、info、notice、warning、error、critical、alert、emergency。

默认情况下，服务会记录 info 级别及以上的日志。可通过 MCP_LOG_LEVEL 控制最低级别，也可在运行时通过 MCP logging/setLevel 请求动态调整。

在建立 MCP 会话之前（例如在初始化连接池期间），日志会回退到 stderr。

---

🌐 高级网络与远程连接

按照设计，tokenlite-mysql-mcp 遵循 Unix 哲学：它只做一件事（由 AI 驱动的 MySQL 交互），并通过标准 stdio 传输安全地完成这项工作。它有意避免在代码库中加入 HTTP 服务或内置 SSH 客户端，以免代码库变得臃肿。

如果你需要连接远程数据库，或通过网络公开此服务，以下是推荐的企业级替代方案：

1. 连接远程数据库（SSH 隧道）

我们建议使用原生操作系统隧道，而不是嵌入 SSH 库。这样更安全，能够遵循你的 ~/.ssh/config，并支持高级身份验证方式（2FA、硬件密钥）。

只需打开终端并运行：

ssh -N -L 3306:127.0.0.1:3306 [email protected]

然后，将 tokenlite-mysql-mcp 指向 localhost 和端口 3306。

2. 通过 HTTP/网络公开 MCP 服务

如果你需要在云端（AWS、GCP）托管此 MCP 服务，并让多个 Claude 桌面客户端通过 HTTP/SSE 远程连接，请勿修改此代码库来添加 Express/HTTP 逻辑。 相反，请使用 mcp-proxy 等标准开源 MCP 代理来封装进程。这样可以将传输层安全与 AI 逻辑清晰分离。

🐛 故障排除

错误：OptimizerError: Full table scan detected... 大模型尝试执行需要扫描数千行且未使用索引的查询。 解决方案：使用 explain_query 查看完整的 EXPLAIN 输出，并了解查询被阻止的原因。使用带索引的 WHERE 子句重写查询。如果确实需要扫描整张表，请在配置中提高 MCP_EXPLAIN_MAX_SCAN_ROWS。若要提高每次查询返回的行数，请单独调整 MCP_QUERY_ROW_LIMIT。

错误：calling "initialize": invalid character... 这表示 MCP JSON-RPC 协议发生崩溃。请确保传入了正确的数据库凭据，并且数据库正在运行，且可从 MCP 服务运行所在的机器访问。

---

为 AI 工程时代打造。

---