1. 为什么要在本地跑一个 MCP 客户端连 SQLiteMCPModel Context Protocol是让 AI 智能体标准化调用外部工具与数据源的协议你可以把它理解成智能体的“工具箱接口”模型负责思考MCP 负责把“查数据库、写数据库”这类动作变成可被调用的工具。SQLite 则是本地最省事的结构化存储一个文件就是一个库不需要额外起服务。把这两者拼起来再配一条统一的 API 通道就能做出一个完全本地、数据不出机器的数据库对话智能体。这套方案适合谁适合手里有一堆本地数据订单、日志、设备台账、测试数据想用自然语言查询的开发者适合在做 Agent 应用、需要给智能体接一个真实数据源的同学也适合想先跑通 MCP 全链路、再迁移到 MySQL/PostgreSQL 的工程团队。整条链路里模型侧走本地推理工具侧走本地 MCP 服务而模型请求的统一出口用 TaoToken 的 API 通道来承接这样你既保留了本地数据的私密性又不用为每个模型供应商单独写一套鉴权和重试逻辑。我试过的坑是一开始把数据库路径写成相对路径MCP 服务被智能体以子进程方式拉起时工作目录变了结果连到了一个空的 test.db查出来永远是 0 行。后面统一改成绝对路径才稳定。所以下面所有配置里的路径建议你都用绝对路径。2. TaoToken 前置准备拿到统一 API 通道TaoToken 在这里扮演的角色是“模型请求的统一入口”。你的 MCP 客户端本身不直接关心底层是哪个模型只把请求发到 TaoToken 的 API 地址由它来路由。这样做的好处是本地 MCP 服务只管工具调用模型调用集中在一处配置换模型、加模型都不用动业务代码。第一步去控制台创建 API Key。打开 https://taotoken.net/console 登录后在 API Keys 页面新建一个密钥复制出来保存好后面配置里要用。密钥只显示一次丢了就重新建一个。第二步确认你要用的模型名。在模型对话页面可以先手动试一句确认这个模型在你的账号下可用https://taotoken.net/models 。把模型名记下来比如常见的对话模型或代码模型填到后面的 config.toml 里。第三步如果你后面要做长期编码或 Agent 任务建议顺手了解一下 Coding Plan它更适合高频、长上下文的场景https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 遇到参数不确定时以文档为准。这里要强调一点TaoToken 是合规的 API 服务入口你只需要按文档填 base_url 和 api_key不要自己拼任何非官方的转发地址。API 根地址统一用 https://taotoken.net/api 注意这个地址后面不加任何查询参数。3. 可复制的 config.toml 骨架下面这份 config.toml 是给 MCP 客户端用的骨架核心是三块模型通道指向 TaoToken、MCP 服务定义SQLite、以及运行参数。你可以直接复制把 api_key、model、数据库路径换成自己的。# config.toml —— 本地 MCP 客户端配置骨架 [llm] # 统一走 TaoToken 的 API 通道 provider openai_compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model 你的模型名 temperature 0.2 max_tokens 2048 timeout 60 [agent] name sqlite-local-agent system_prompt 你是一个本地数据库助手。你可以调用 SQLite 工具来查询和修改数据。 规则 1. 只操作被授权的数据库文件不要尝试访问其他路径。 2. 写操作前先用 SELECT 确认影响范围。 3. 返回结果时用简洁的中文说明你执行了什么、影响了几行。 [mcp_servers.sqlite] # 用绝对路径避免子进程工作目录变化导致连错库 command python args [-m, mcp_server_sqlite, --db, /Users/you/data/app.db] transport stdio enabled true [runtime] log_level info max_tool_rounds 8几个参数说明一下。base_url 固定为 https://taotoken.net/api 不要加斜杠后缀之外的路径。transport 用 stdio 是最省事的本地方式MCP 服务作为子进程被拉起通过标准输入输出通信不需要开端口。max_tool_rounds 控制一次对话里最多调用几轮工具太小会导致复杂查询被截断太大又可能让智能体反复试错8 是个比较稳的起点。如果你用的是 Claude Code 这类客户端配置文件的字段名会不一样但本质相同把模型通道指向 TaoToken把 MCP 服务注册进去。Claude Code 的接入方式可以参考 https://taotoken.net/claude-code-anthropic 里面给了对应的字段映射。4. settings.json 配置片段与 MCP 服务注册有些客户端尤其是 VS Code 系插件和部分 Agent 框架读的是 settings.json而不是 config.toml。下面给一份等价的 settings.json 片段字段按常见约定命名你按自己客户端的实际 schema 微调即可。{ mcp: { servers: { sqlite: { command: python, args: [-m, mcp_server_sqlite, --db, /Users/you/data/app.db], transport: stdio, env: { SQLITE_READONLY: 0 } } } }, llm: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: 你的模型名 }, agent: { maxToolRounds: 8, logLevel: info } }注意 env 里的 SQLITE_READONLY如果你只想让智能体查数据、不允许改数据把它设成 1这样即使模型生成了 INSERT/UPDATE工具层也会拒绝执行。这是本地场景里非常实用的一道闸。MCP 服务本身可以用现成的 SQLite MCP server也可以自己写一个最小实现。自己写的好处是可控下面是一个精简版暴露两个工具查询和写入。# sqlite_mcp_server.py —— 最小 SQLite MCP 服务 import sqlite3 import json from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent DB_PATH /Users/you/data/app.db app Server(sqlite-local) def get_conn(): conn sqlite3.connect(DB_PATH) conn.row_factory sqlite3.Row return conn app.list_tools() async def list_tools(): return [ Tool( namequery, description执行 SELECT 查询返回 JSON 数组, inputSchema{ type: object, properties: {sql: {type: string}}, required: [sql], }, ), Tool( nameexecute, description执行 INSERT/UPDATE/DELETE返回影响行数, inputSchema{ type: object, properties: {sql: {type: string}}, required: [sql], }, ), ] app.call_tool() async def call_tool(name: str, arguments: dict): conn get_conn() try: cur conn.cursor() if name query: cur.execute(arguments[sql]) rows [dict(r) for r in cur.fetchall()] return [TextContent(typetext, textjson.dumps(rows, ensure_asciiFalse))] if name execute: cur.execute(arguments[sql]) conn.commit() return [TextContent(typetext, textfaffected_rows{cur.rowcount})] return [TextContent(typetext, textfunknown tool: {name})] finally: conn.close() async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: import asyncio asyncio.run(main())把 DB_PATH 换成你的绝对路径然后用 python sqlite_mcp_server.py 就能作为 stdio 服务被客户端拉起。config.toml 里的 args 相应改成 [/绝对路径/sqlite_mcp_server.py]。5. 连接验证与对话测试从 0 行到正确结果配置写完先别急着让智能体自由发挥按下面三步验证能快速定位问题出在哪一层。第一步单独验证 MCP 服务能起来。在终端直接跑python -m mcp_server_sqlite --db /Users/you/data/app.db如果它没有立刻报错退出说明服务本身没问题。如果报 ModuleNotFoundError先装依赖pip install mcp mcp-server-sqlite第二步验证 TaoToken 通道能通。用 curl 打一次模型列表或对话接口确认密钥和地址正确curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到模型输出说明通道没问题。如果返回 401检查密钥返回 404检查 base_url 是不是写成了带多余路径的形式。第三步跑端到端对话。启动你的 MCP 客户端输入一句自然语言比如“帮我看看 users 表里有多少条记录”。正常的话你会看到客户端先调用 query 工具拿到结果再用中文回答你。整个过程在日志里能看到工具调用记录形如 tool_call: query, args: {sql: SELECT COUNT(*) FROM users}。为了确认写入链路也通再试一句“往 users 表插入一条 name 为 test 的记录”然后自己用 sqlite3 命令行查一下sqlite3 /Users/you/data/app.db SELECT * FROM users WHERE nametest;能看到这条记录说明从自然语言到数据库落盘的完整链路已经打通。6. 本篇常见错排查报错一no such table: xxx。九成是数据库路径不对MCP 服务连到了另一个空库。把 config.toml 和 settings.json 里的路径都改成绝对路径再用ls -l /你的路径/app.db确认文件真实存在。报错二Connection refused 或超时。这是模型通道的问题不是 MCP 的问题。检查 base_url 是否为 https://taotoken.net/api 密钥是否过期以及本机网络是否能正常访问该地址。注意不要在 base_url 后面拼 /v1/chat/completions 之外的奇怪路径。报错三智能体反复调用同一个工具、停不下来。把 max_tool_rounds 调小到 5 左右同时在 system_prompt 里明确“拿到结果后直接回答不要重复查询”。提示词对工具调用轮次的影响比想象中大。报错四写操作被拒绝。检查 env 里的 SQLITE_READONLY 是不是设成了 1。这个开关是故意设计的保护要写入就改成 0。报错五中文返回乱码。在 MCP 服务里返回 JSON 时加 ensure_asciiFalse客户端侧统一按 UTF-8 解析。SQLite 本身对 UTF-8 支持很好乱码基本都出在序列化环节。排查顺序建议固定为先单独起 MCP 服务 → 再 curl 模型通道 → 最后跑端到端。这样任何一层出问题都能立刻定位不用在整条链路上瞎猜。7. 下一步把通道和工具都管起来链路跑通之后日常维护其实就两件事管好 API Key管好工具权限。密钥建议按用途分开建本地调试一个、长期任务一个出问题能单独吊销。工具权限上读多写少的场景直接把 SQLITE_READONLY 打开需要写入时再临时放开比事后审计省心得多。如果你准备把这个 MCP 客户端用到长期编码或 Agent 任务里建议把模型通道切到 Coding Plan长上下文和高频调用下更稳https://taotoken.net/coding-plan 。密钥管理统一在 https://taotoken.net/api-keys 处理接入细节以 https://taotoken.net/doc 为准。想先手动验证某个模型的表现可以直接在 https://taotoken.net/models 里对话测试确认没问题再写进 config.toml。整套配置里唯一需要记住的地址就是 https://taotoken.net/api 其余都是围绕它的参数调整。