1. 为什么我要把 MySQL 操作交给 MCP 服务MCP 是 Anthropic 推出的开放协议全称 Model Context Protocol它做的事情可以用一句话概括给大模型接外部数据和工具定一套标准接口。你可以把它理解成 AI 世界的 USB-C以前每个工具都要单独写适配现在只要按 MCP 协议暴露能力任何支持 MCP 的客户端都能直接调用。MCP 服务操作 MySQL 数据库这个场景适合那些想让 AI 助手直接查表结构、跑 SQL、做增删改查又不想把数据库账号密码散落在各个工具配置里的开发者。我这次要跑通的链路是TaoToken 统一 Key 作为模型调用通道本地起一个 MySQL MCP Server客户端通过 MCP 协议连接这个 Server然后让模型根据自然语言生成 SQL 并执行。整条链路里TaoToken 负责模型侧的鉴权和计费MCP Server 负责数据库侧的工具暴露两边解耦换模型不用动数据库配置换数据库也不用改模型接入。这篇文章会交付可复制的 MCP 服务配置骨架、settings.json 片段、连接验证动作和查询测试步骤。你跟着做能在一个下午跑通 MCP MySQL 的完整链路。适合有 Python 基础、用过 Docker、想让 AI 直接操作数据库的读者。2. TaoToken 前置统一 Key 与 API 通道准备在开始写 MCP Server 之前先把模型侧的通道准备好。TaoToken 在这里的角色是统一 Key 管理你不需要为每个模型单独申请账号一个 Key 就能调用多种模型。对于 MCP 场景来说这意味着你的客户端配置里只需要维护一份凭证。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去之后找到 API Keys 页面新建一个 Key 并复制保存。这个 Key 后面会用在客户端的模型配置里。API 的基础地址是 https://taotoken.net/api 注意这个地址不加 UTM 参数直接填在客户端的 Base URL 字段即可。如果你用的是 Claude Code 或者 Anthropic 风格的客户端接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有不同客户端的配置示例。注意API Key 只显示一次创建后立刻保存到安全的地方。不要把它写进会提交到 Git 的配置文件里。模型侧准备好之后你可以先用模型对话功能验证 Key 是否可用。打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 选一个模型发一条测试消息能正常返回就说明通道没问题。这一步很重要因为后面 MCP 链路出问题时你需要先排除是模型通道的问题还是 MCP Server 的问题。如果你打算长期用 MCP 做编码或 Agent 任务可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它适合高频调用的场景比按次计费更划算。3. 可复制配置MySQL MCP Server 骨架与 settings.json这一章是核心我会把 MCP Server 的目录结构、依赖、环境变量、服务端代码骨架和客户端配置都列出来。你直接复制改参数就能用。3.1 目录结构与依赖安装先建目录我习惯把 MCP Server 放在独立目录里避免和别的项目混在一起。mkdir sql_mcp_server_pro cd sql_mcp_server_pro touch .env pkg.txt server.pypkg.txt 里写依赖mcp mysql-connector-python uvicorn python-dotenv starlette然后创建虚拟环境并安装conda create -n mcp_env python3.12.4 conda activate mcp_env pip install -r pkg.txt用 conda 是为了隔离依赖避免和你系统里的 Python 包冲突。如果你不用 conda用 venv 也行命令换成python -m venv mcp_env然后激活。3.2 环境变量与数据库准备.env 文件里写数据库连接信息MYSQL_HOST127.0.0.1 MYSQL_PORT3306 MYSQL_USERroot MYSQL_PASSWORDyourpassword MYSQL_DATABASEtest数据库这边我用 Docker 起一个 MySQL 实例这样不污染本机环境。先拉镜像docker pull mysql:latest mkdir -p /mysql/conf在 /mysql/conf 下建 my.cnf关键配置如下[client] default_character_setutf8mb4 [mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_general_ci bind-address0.0.0.0 max_connections400 max_allowed_packet128M然后启动容器docker run -dit -p 3306:3306 \ -v /mysql/conf:/etc/mysql/conf.d \ -e MYSQL_ROOT_PASSWORDyourpassword \ --name tzy-mysql mysql进容器建一个 test 库docker exec -it tzy-mysql /bin/bash mysql -u root -p CREATE DATABASE test CHARACTER SET utf8mb4;字符集一定要用 utf8mb4不然后面存中文注释或者特殊字符会出问题。我踩过的坑就是一开始用了 utf8结果表注释里的中文变成乱码排查了半天。3.3 MCP Server 代码骨架server.py 的核心逻辑是定义工具列表每个工具对应一个数据库操作函数通过 SSE 传输暴露给客户端。下面是精简后的骨架你可以直接复制import os import uvicorn from mcp.server.sse import SseServerTransport from mysql.connector import connect, Error from mcp.server import Server from mcp.types import Tool, TextContent from starlette.applications import Starlette from starlette.routing import Route, Mount from dotenv import load_dotenv def get_db_config(): load_dotenv() config { host: os.getenv(MYSQL_HOST, 127.0.0.1), port: int(os.getenv(MYSQL_PORT, 3306)), user: os.getenv(MYSQL_USER), password: os.getenv(MYSQL_PASSWORD), database: os.getenv(MYSQL_DATABASE), } if not all([config[user], config[password], config[database]]): raise ValueError(缺少必需的数据库配置) return config def execute_sql(query: str) - list[TextContent]: config get_db_config() try: with connect(**config) as conn: with conn.cursor() as cursor: statements [s.strip() for s in query.split(;) if s.strip()] results [] for statement in statements: cursor.execute(statement) if cursor.description: columns [desc[0] for desc in cursor.description] rows cursor.fetchall() formatted [ ,.join(NULL if v is None else str(v) for v in row) for row in rows ] results.append(\n.join([,.join(columns)] formatted)) else: conn.commit() results.append(f执行成功影响行数: {cursor.rowcount}) return [TextContent(typetext, text\n---\n.join(results))] except Error as e: return [TextContent(typetext, textf执行出错: {str(e)})] app Server(operateMysql) app.list_tools() async def list_tools() - list[Tool]: return [ Tool( nameexecute_sql, description在MySQL数据库上执行SQL语句, inputSchema{ type: object, properties: { query: {type: string, description: 要执行的SQL语句} }, required: [query], }, ), ] app.call_tool() async def call_tool(name: str, arguments: dict) - list[TextContent]: if name execute_sql: query arguments.get(query) if not query: raise ValueError(缺少查询语句) return execute_sql(query) raise ValueError(f未知工具: {name}) sse SseServerTransport(/messages/) async def handle_sse(request): async with sse.connect_sse( request.scope, request.receive, request._send ) as streams: await app.run(streams[0], streams[1], app.create_initialization_options()) starlette_app Starlette( debugTrue, routes[ Route(/sse, endpointhandle_sse), Mount(/messages/, appsse.handle_post_message), ], ) if __name__ __main__: uvicorn.run(starlette_app, host0.0.0.0, port9000)这个骨架只暴露了一个 execute_sql 工具够你跑通链路。如果你想加表结构查询、锁查询之类的工具照着 list_tools 和 call_tool 的模式扩展就行。3.4 客户端 settings.json 配置片段启动服务python server.py看到 uvicorn 输出监听 9000 端口就说明起来了。然后在客户端里配置 MCP 服务器。以支持 MCP 的客户端为例settings.json 里加一段{ mcpServers: { mysql-local: { url: http://127.0.0.1:9000/sse, transport: sse } } }如果你的客户端用的是命令启动方式配置改成{ mcpServers: { mysql-local: { command: python, args: [/path/to/sql_mcp_server_pro/server.py], env: { MYSQL_HOST: 127.0.0.1, MYSQL_PORT: 3306, MYSQL_USER: root, MYSQL_PASSWORD: yourpassword, MYSQL_DATABASE: test } } } }两种方式选一种SSE 方式适合服务常驻命令方式适合客户端自己管理进程。模型侧的 Base URL 填 https://taotoken.net/api API Key 填你在控制台创建的那个。4. 验证请求与成功结果配置完成后先做连接验证再做查询测试。不要跳过验证直接上复杂 SQL不然出问题你分不清是连接问题还是 SQL 问题。4.1 连接验证在客户端里新建一个对话选中刚才配置的 mysql-local 服务器。先发一条最简单的指令列出当前数据库里所有的表模型会调用 execute_sql 工具实际执行的 SQL 是SHOW TABLES;。如果返回空结果或者表列表说明链路通了。如果报连接错误检查 .env 里的 host 和 portDocker 起的 MySQL 如果客户端也在宿主机用 127.0.0.1 就行如果客户端在容器里要用宿主机的局域网 IP。4.2 建表与插入测试链路通了之后做一轮完整的增删改查。先建表创建一张员工表表名用英文字段包括姓名、年龄、工资然后插入10条虚拟数据模型生成的 SQL 大致是CREATE TABLE employees ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50), age INT, salary DECIMAL(10,2) ); INSERT INTO employees (name, age, salary) VALUES (张三, 28, 8500.00), (李四, 32, 12000.00), (王五, 26, 7200.00), (赵六, 35, 15000.00), (孙七, 29, 9800.00), (周八, 31, 11000.00), (吴九, 27, 8000.00), (郑十, 33, 13500.00), (钱一, 30, 10500.00), (刘二, 34, 14200.00);执行成功后工具会返回影响行数。然后做查询查询工资最高的5名员工按工资降序排列对应的 SQLSELECT name, age, salary FROM employees ORDER BY salary DESC LIMIT 5;返回结果应该是 CSV 格式的文本列名在第一行数据在后面。如果你看到类似下面的输出说明查询链路完全通了name,age,salary 赵六,35,15000.00 刘二,34,14200.00 郑十,33,13500.00 李四,32,12000.00 周八,31,11000.004.3 更新与删除测试继续测试写操作把张三的工资改成 9000然后删除年龄大于 33 的员工模型会生成 UPDATE 和 DELETE 语句工具执行后返回影响行数。你可以再查一次全表确认结果。这一轮下来增删改查四个动作都覆盖了。5. 本篇常见错排查跑 MCP MySQL 链路时报错集中在几个地方。我把最常见的列出来你对照排查。连接被拒绝Connection refused先确认 MySQL 容器在跑docker ps看状态。然后确认端口映射对不对docker run时的-p 3306:3306不能少。如果客户端和 MySQL 不在同一台机器检查防火墙和 bind-addressmy.cnf 里要设成 0.0.0.0。认证失败Access denied检查 .env 里的用户名密码注意 MySQL 8 的 root 密码策略可能要求复杂密码。如果用的是 Docker 环境变量设的密码确认MYSQL_ROOT_PASSWORD和 .env 里一致。字符集乱码建库建表时用 utf8mb4连接配置里也指定 charset。mysql-connector-python 可以在 connect 参数里加charsetutf8mb4。如果已经建了表用ALTER TABLE ... CONVERT TO CHARACTER SET utf8mb4;改。MCP 工具不显示客户端里看不到 execute_sql 工具先确认 server.py 启动没报错然后确认客户端配置的 URL 或命令路径正确。SSE 方式要确认 9000 端口没被占用命令方式要确认 python 路径是虚拟环境里的那个。模型不调用工具模型收到指令后只回复文字不调工具可能是工具描述不够清晰或者模型本身对 function calling 支持不好。把工具 description 写具体一点比如「在MySQL数据库上执行SQL语句支持SELECT/INSERT/UPDATE/DELETE」。如果还不行换一个对工具调用支持更好的模型。SQL 执行超时大表查询或者锁等待会导致超时。在 connect 参数里加connection_timeout或者在 SQL 层面加 LIMIT。生产库上跑 MCP 一定要加只读账号或者查询限制避免误操作。注意MCP Server 直连生产库有风险建议先在测试库跑通生产环境用只读账号写操作走审批流程。6. 继续深入的方向链路跑通之后你可以往几个方向扩展。一是加更多工具比如 get_table_desc 查表结构、get_lock_tables 查锁等待这些在排查问题时很有用。二是把 MCP Server 部署到内网服务器客户端通过内网地址连接这样团队里多个人可以共用一套数据库工具。三是结合 Coding Plan 做长期编码任务让模型在写代码时直接查数据库结构减少来回切换工具的成本。模型侧的统一 Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 你可以在这里管理多个 Key给不同项目分配不同的额度。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的详细配置说明。如果遇到 MCP 接入问题先查文档里的排障章节大部分连接和鉴权问题都有覆盖。整套配置跑下来最花时间的其实是环境准备和字符集排查MCP Server 本身的代码量并不大。你把骨架跑通之后加工具就是复制粘贴改函数的事。