1. 为什么你需要一个 MySQL MCP 调试链路如果你正在做 AI 应用开发大概率遇到过这个场景想让大模型查一下业务库里的订单状态、用户列表或者日志统计结果发现模型只能“空口说白话”根本碰不到真实数据。传统做法是手写一套 REST API再让模型通过 Function Calling 去调但每个数据源都要重复一遍参数定义、鉴权、错误处理维护成本高得离谱。MCPModel Context Protocol模型上下文协议就是来解决这个问题的。它定义了一套标准协议让大模型以统一方式调用外部工具、数据库、文件系统。而 FastMCP 是 Python 生态里最顺手的 MCP 服务开发框架用装饰器就能把普通函数注册成模型可调用的工具JSON-RPC 通信、参数校验、服务注册这些脏活它全包了。这篇内容聚焦一件事用 FastMCP Python 从零搭一个 MySQL MCP 服务并跑通“注册工具 → 本地调试 → 查询返回”的完整链路。适合需要快速验证工具调用与数据库查询的开发者尤其是手头有测试库、想半天内看到模型真的查出数据的人。下面所有代码和命令都可以直接复制改掉连接配置就能用。2. 前置准备Python 环境、MySQL 测试库与 TaoToken 接入动手之前先把三样东西备齐后面调试会顺很多。第一是 Python 3.11 及以上版本。FastMCP 依赖较新的类型注解和异步能力3.10 以下容易在启动时报语法或依赖错误。用python --version确认一下不够就升级。第二是一个能连上的 MySQL 实例。本地 Docker 起一个最省事或者用你已有的测试库。建一个test_db再建一张users表塞两行数据即可CREATE DATABASE IF NOT EXISTS test_db DEFAULT CHARSET utf8mb4; USE test_db; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64), email VARCHAR(128) ); INSERT INTO users (name, email) VALUES (hello, hellotest.com), (mcp, mcptest.com);第三是模型侧接入。MCP 服务本身只负责暴露工具真正发起调用的是大模型客户端。你可以通过 TaoToken 的模型对话能力来验证工具调用是否被正确触发API 地址是https://taotoken.net/api。如果你打算长期做编码类 Agent 调试可以了解下 Coding Plan只是临时验证模型能否调通工具用模型对话入口就够了。密钥在控制台的 API Keys 页面生成接入文档里有各客户端的配置示例。注意MCP 服务会执行 SQL务必只连测试库别把生产库配置写进去。后面第 5 节会讲白名单限制。3. 可复制配置FastMCP 服务骨架与 MySQL 连接先装依赖两个包就够pip install fastmcp pymysql项目结构保持极简一个文件加一个依赖清单mcp-mysql/ ├─ mysql_mcp.py └─ requirements.txtrequirements.txt内容fastmcp pymysql核心服务文件mysql_mcp.py如下连接配置抽成字典工具函数用app.tool()注册import pymysql from fastmcp import FastMCP app FastMCP(MySQL MCP) DB_CONFIG { host: 127.0.0.1, user: root, port: 3306, password: your_password, database: test_db, charset: utf8mb4, cursorclass: pymysql.cursors.DictCursor, } def run_query(sql: str): conn pymysql.connect(**DB_CONFIG) try: with conn.cursor() as cursor: cursor.execute(sql) if sql.strip().lower().startswith(select): return {rows: cursor.fetchall()} conn.commit() return {status: success, rows_affected: cursor.rowcount} finally: conn.close() app.tool() def query_mysql(sql: str) - dict: 执行 MySQL 查询语句 参数: sql: 要执行的 SQL 语句 (SELECT / INSERT / UPDATE / DELETE) try: return run_query(sql) except Exception as e: return {error: str(e)} if __name__ __main__: app.run(transportstdio)几个关键点解释一下。transportstdio表示服务通过标准输入输出与客户端通信这是本地调试最常用的模式MCP Inspector 和多数客户端都支持。DictCursor让查询结果直接是字典列表序列化成 JSON 时不会丢字段。工具函数返回dict而不是字符串FastMCP 会自动包装成 MCP 协议要求的content和structuredContent结构客户端解析起来更省心。如果你要支持多库切换可以在工具签名里加db_name: str参数然后在run_query里覆盖DB_CONFIG[database]。但调试阶段建议先跑通单库减少变量。4. 验证请求用 MCP Inspector 跑通查询返回服务写完了怎么确认它真的能被调用用 MCP Inspector这是官方提供的交互式调试工具能实时展示服务暴露的工具、测试调用、查看输入输出和错误日志。先确保本机有 Node 20然后直接用它拉起你的服务npx modelcontextprotocol/inspector python /your/path/mysql_mcp.py把路径换成你实际的mysql_mcp.py绝对路径。命令执行后会启动一个本地调试页面浏览器自动打开。在页面左侧能看到query_mysql这个工具点进去在参数框输入select * from users点击调用右侧会返回类似这样的结果{ content: [ { type: text, text: {\rows\:[{\id\:1,\name\:\hello\,\email\:\hellotest.com\},{\id\:2,\name\:\mcp\,\email\:\mcptest.com\}]} } ], structuredContent: { rows: [ {id: 1, name: hello, email: hellotest.com}, {id: 2, name: mcp, email: mcptest.com} ] }, isError: false }看到isError: false且rows里有数据说明从工具注册到数据库查询返回的链路已经通了。接着可以试增删改比如insert into users (name, email) values (tester, testertest.com)返回里会出现rows_affected: 1。再查一次确认数据落库。这一步跑通后你就可以把同一个服务接到支持 MCP 的模型客户端上让模型通过 TaoToken 的模型对话入口发起工具调用观察它是否能正确选择query_mysql并传入 SQL。5. 本篇常见错排查调试过程中最容易卡在几个地方我按出现频率排一下。连接被拒绝或超时先确认 MySQL 端口。很多本地环境 MySQL 跑在 3308 或 3307 而不是默认 3306DB_CONFIG里的port要和实际一致。用mysql -h 127.0.0.1 -P 3306 -u root -p手动连一次能连上再跑 MCP。Inspector 启动后看不到工具多半是 Python 路径不对或者fastmcp没装进当前解释器。用which python确认路径再pip show fastmcp看是否安装。如果服务启动时抛异常Inspector 页面会有日志先看报错再改代码。返回结果里中文乱码连接配置加charsetutf8mb4建库建表也用utf8mb4。两边编码不一致时DictCursor返回的字符串会变成问号或乱码。SQL 执行报语法错误但语句看着没问题检查传入的 SQL 是否带了多余引号或换行。Inspector 的参数框里直接贴纯 SQL不要包 JSON 引号。另外query_mysql的 docstring 会影响模型对工具的理解描述写清楚“支持 SELECT/INSERT/UPDATE/DELETE”能减少模型传错参数。安全提醒示例里的query_mysql能执行任意 SQL直接暴露给不受控的模型有风险。建议在run_query里加白名单比如只允许select开头或者用正则限制表名。要支持多库时再加db_name参数但每个库的连接权限要单独控制。6. 把链路接到真实模型调用上本地 Inspector 验证通过只是第一步真正要确认的是模型能不能在对话里自主选择这个工具。把 MCP 服务配置到你的模型客户端后发一句“帮我查一下 test_db 里 users 表有哪些人”观察它是否调用query_mysql并传入正确的 SQL。如果模型没触发工具通常是工具描述不够明确把 docstring 里的参数说明写得更具体一些。密钥管理上TaoToken 的 API Keys 页面可以生成和轮换密钥接入文档里有 stdio 和 HTTP 两种 MCP 接入方式的配置模板。调试阶段用模型对话快速验证长期跑编码或 Agent 任务再考虑 Coding Plan按自己的调用量选就行。整条链路跑通后换数据源只需要改DB_CONFIG和工具函数协议层的东西 FastMCP 都帮你兜住了。
MCP服务开发终极指南：用FastMCP+Python从零搭建MySQL调试链路，收藏这一篇就够了！
1. 为什么你需要一个 MySQL MCP 调试链路如果你正在做 AI 应用开发大概率遇到过这个场景想让大模型查一下业务库里的订单状态、用户列表或者日志统计结果发现模型只能“空口说白话”根本碰不到真实数据。传统做法是手写一套 REST API再让模型通过 Function Calling 去调但每个数据源都要重复一遍参数定义、鉴权、错误处理维护成本高得离谱。MCPModel Context Protocol模型上下文协议就是来解决这个问题的。它定义了一套标准协议让大模型以统一方式调用外部工具、数据库、文件系统。而 FastMCP 是 Python 生态里最顺手的 MCP 服务开发框架用装饰器就能把普通函数注册成模型可调用的工具JSON-RPC 通信、参数校验、服务注册这些脏活它全包了。这篇内容聚焦一件事用 FastMCP Python 从零搭一个 MySQL MCP 服务并跑通“注册工具 → 本地调试 → 查询返回”的完整链路。适合需要快速验证工具调用与数据库查询的开发者尤其是手头有测试库、想半天内看到模型真的查出数据的人。下面所有代码和命令都可以直接复制改掉连接配置就能用。2. 前置准备Python 环境、MySQL 测试库与 TaoToken 接入动手之前先把三样东西备齐后面调试会顺很多。第一是 Python 3.11 及以上版本。FastMCP 依赖较新的类型注解和异步能力3.10 以下容易在启动时报语法或依赖错误。用python --version确认一下不够就升级。第二是一个能连上的 MySQL 实例。本地 Docker 起一个最省事或者用你已有的测试库。建一个test_db再建一张users表塞两行数据即可CREATE DATABASE IF NOT EXISTS test_db DEFAULT CHARSET utf8mb4; USE test_db; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(64), email VARCHAR(128) ); INSERT INTO users (name, email) VALUES (hello, hellotest.com), (mcp, mcptest.com);第三是模型侧接入。MCP 服务本身只负责暴露工具真正发起调用的是大模型客户端。你可以通过 TaoToken 的模型对话能力来验证工具调用是否被正确触发API 地址是https://taotoken.net/api。如果你打算长期做编码类 Agent 调试可以了解下 Coding Plan只是临时验证模型能否调通工具用模型对话入口就够了。密钥在控制台的 API Keys 页面生成接入文档里有各客户端的配置示例。注意MCP 服务会执行 SQL务必只连测试库别把生产库配置写进去。后面第 5 节会讲白名单限制。3. 可复制配置FastMCP 服务骨架与 MySQL 连接先装依赖两个包就够pip install fastmcp pymysql项目结构保持极简一个文件加一个依赖清单mcp-mysql/ ├─ mysql_mcp.py └─ requirements.txtrequirements.txt内容fastmcp pymysql核心服务文件mysql_mcp.py如下连接配置抽成字典工具函数用app.tool()注册import pymysql from fastmcp import FastMCP app FastMCP(MySQL MCP) DB_CONFIG { host: 127.0.0.1, user: root, port: 3306, password: your_password, database: test_db, charset: utf8mb4, cursorclass: pymysql.cursors.DictCursor, } def run_query(sql: str): conn pymysql.connect(**DB_CONFIG) try: with conn.cursor() as cursor: cursor.execute(sql) if sql.strip().lower().startswith(select): return {rows: cursor.fetchall()} conn.commit() return {status: success, rows_affected: cursor.rowcount} finally: conn.close() app.tool() def query_mysql(sql: str) - dict: 执行 MySQL 查询语句 参数: sql: 要执行的 SQL 语句 (SELECT / INSERT / UPDATE / DELETE) try: return run_query(sql) except Exception as e: return {error: str(e)} if __name__ __main__: app.run(transportstdio)几个关键点解释一下。transportstdio表示服务通过标准输入输出与客户端通信这是本地调试最常用的模式MCP Inspector 和多数客户端都支持。DictCursor让查询结果直接是字典列表序列化成 JSON 时不会丢字段。工具函数返回dict而不是字符串FastMCP 会自动包装成 MCP 协议要求的content和structuredContent结构客户端解析起来更省心。如果你要支持多库切换可以在工具签名里加db_name: str参数然后在run_query里覆盖DB_CONFIG[database]。但调试阶段建议先跑通单库减少变量。4. 验证请求用 MCP Inspector 跑通查询返回服务写完了怎么确认它真的能被调用用 MCP Inspector这是官方提供的交互式调试工具能实时展示服务暴露的工具、测试调用、查看输入输出和错误日志。先确保本机有 Node 20然后直接用它拉起你的服务npx modelcontextprotocol/inspector python /your/path/mysql_mcp.py把路径换成你实际的mysql_mcp.py绝对路径。命令执行后会启动一个本地调试页面浏览器自动打开。在页面左侧能看到query_mysql这个工具点进去在参数框输入select * from users点击调用右侧会返回类似这样的结果{ content: [ { type: text, text: {\rows\:[{\id\:1,\name\:\hello\,\email\:\hellotest.com\},{\id\:2,\name\:\mcp\,\email\:\mcptest.com\}]} } ], structuredContent: { rows: [ {id: 1, name: hello, email: hellotest.com}, {id: 2, name: mcp, email: mcptest.com} ] }, isError: false }看到isError: false且rows里有数据说明从工具注册到数据库查询返回的链路已经通了。接着可以试增删改比如insert into users (name, email) values (tester, testertest.com)返回里会出现rows_affected: 1。再查一次确认数据落库。这一步跑通后你就可以把同一个服务接到支持 MCP 的模型客户端上让模型通过 TaoToken 的模型对话入口发起工具调用观察它是否能正确选择query_mysql并传入 SQL。5. 本篇常见错排查调试过程中最容易卡在几个地方我按出现频率排一下。连接被拒绝或超时先确认 MySQL 端口。很多本地环境 MySQL 跑在 3308 或 3307 而不是默认 3306DB_CONFIG里的port要和实际一致。用mysql -h 127.0.0.1 -P 3306 -u root -p手动连一次能连上再跑 MCP。Inspector 启动后看不到工具多半是 Python 路径不对或者fastmcp没装进当前解释器。用which python确认路径再pip show fastmcp看是否安装。如果服务启动时抛异常Inspector 页面会有日志先看报错再改代码。返回结果里中文乱码连接配置加charsetutf8mb4建库建表也用utf8mb4。两边编码不一致时DictCursor返回的字符串会变成问号或乱码。SQL 执行报语法错误但语句看着没问题检查传入的 SQL 是否带了多余引号或换行。Inspector 的参数框里直接贴纯 SQL不要包 JSON 引号。另外query_mysql的 docstring 会影响模型对工具的理解描述写清楚“支持 SELECT/INSERT/UPDATE/DELETE”能减少模型传错参数。安全提醒示例里的query_mysql能执行任意 SQL直接暴露给不受控的模型有风险。建议在run_query里加白名单比如只允许select开头或者用正则限制表名。要支持多库时再加db_name参数但每个库的连接权限要单独控制。6. 把链路接到真实模型调用上本地 Inspector 验证通过只是第一步真正要确认的是模型能不能在对话里自主选择这个工具。把 MCP 服务配置到你的模型客户端后发一句“帮我查一下 test_db 里 users 表有哪些人”观察它是否调用query_mysql并传入正确的 SQL。如果模型没触发工具通常是工具描述不够明确把 docstring 里的参数说明写得更具体一些。密钥管理上TaoToken 的 API Keys 页面可以生成和轮换密钥接入文档里有 stdio 和 HTTP 两种 MCP 接入方式的配置模板。调试阶段用模型对话快速验证长期跑编码或 Agent 任务再考虑 Coding Plan按自己的调用量选就行。整条链路跑通后换数据源只需要改DB_CONFIG和工具函数协议层的东西 FastMCP 都帮你兜住了。
