MCP 协议实战：用 Claude Desktop 连本地 SQLite，5 分钟搭一个能查数据的 AI 助手

MCP 协议实战用 Claude Desktop 连本地 SQLite5 分钟搭一个能查数据的 AI 助手本文参与 CSDN「MCP 协议开发实战」征文活动标签#MCP #Model Context Protocol #Claude Desktop #AI Agent前言为什么你该现在学 MCP如果你用过 Claude Desktop、Cursor、或者 Cline大概率遇到过这个场景AI 说我无法访问你的数据库/文件/API请把内容贴给我。MCPModel Context Protocol就是解决这个问题的。它让 AI 能直接调用你本地的工具——查数据库、读文件、调 API——不用你手动复制粘贴。Anthropic 2024 年底开源了这套协议到 2026 年中Cursor、Cline、Claude Desktop、Windsurf 都已经原生支持。学会写一个 MCP Server等于给你的 AI 装上了手。这篇我带你从 0 搭一个能查 SQLite 数据库的 MCP Server接进 Claude Desktop全程不超过 5 分钟。代码可以直接复用到你自己的项目里。一、环境准备1 分钟你需要装好这三样工具版本要求安装命令Python3.10官网下载或pyenv install 3.11uv最新版pip install uvClaude Desktop任意版本官网下载为什么用uv而不是pipMCP 官方 SDK 用uv管理依赖更快且uv run能自动创建虚拟环境省去手动venv的步骤。检查环境python--version# 应该 3.10uv--version# 应该有输出二、5 分钟搭一个能查 SQLite 的 MCP Server第 1 步初始化项目mkdirmcp-sqlite-democdmcp-sqlite-demo uv init uvaddmcp[cli]sqlite3mcp[cli]是官方 Python SDKsqlite3是 Python 内置库实际上不用单独装这里写上是为了 uv 识别。第 2 步准备一个测试数据库先建一个简单的 SQLite 库放点测试数据# init_db.pyimportsqlite3 connsqlite3.connect(demo.db)cconn.cursor()c.execute( CREATE TABLE IF NOT EXISTS orders ( id INTEGER PRIMARY KEY, customer TEXT, amount REAL, status TEXT, created_at TEXT ) )c.executemany(INSERT INTO orders VALUES (?, ?, ?, ?, ?),[(1,张三,299.0,已支付,2026-07-01),(2,李四,1580.0,已发货,2026-07-05),(3,王五,89.0,退款中,2026-07-10),(4,赵六,2300.0,已支付,2026-07-12),(5,张三,599.0,待发货,2026-07-15),])conn.commit()conn.close()print(数据库初始化完成)跑一下uv run python init_db.py第 3 步写 MCP Server核心代码这是全文最关键的一段完整贴出来# server.pyfrommcp.server.fastmcpimportFastMCPimportsqlite3 mcpFastMCP(sqlite-demo)DB_PATHdemo.dbmcp.tool()defquery_orders(customer:str,status:str)-str:查询订单列表。 Args: customer: 客户姓名留空查全部 status: 订单状态已支付/已发货/退款中/待发货留空查全部 Returns: JSON 格式的订单列表字符串 connsqlite3.connect(DB_PATH)cconn.cursor()sqlSELECT id, customer, amount, status, created_at FROM orders WHERE 11params[]ifcustomer:sql AND customer ?params.append(customer)ifstatus:sql AND status ?params.append(status)rowsc.execute(sql,params).fetchall()conn.close()result[{id:r[0],customer:r[1],amount:r[2],status:r[3],date:r[4]}forrinrows]returnstr(result)mcp.tool()defget_order_stats()-str:统计订单总金额、各状态数量。 Returns: 统计摘要字符串 connsqlite3.connect(DB_PATH)cconn.cursor()totalc.execute(SELECT COUNT(*), SUM(amount) FROM orders).fetchone()by_statusc.execute(SELECT status, COUNT(*) FROM orders GROUP BY status).fetchall()conn.close()summaryf总订单数{total[0]}总金额¥{total[1]:.2f}\nsummary状态分布\nfors,ninby_status:summaryf -{s}{n}单\nreturnsummaryif__name____main__:mcp.run()代码解读3 个关键点FastMCP(sqlite-demo)— 创建一个 MCP Server名字随便取mcp.tool()装饰器 — 把普通 Python 函数变成 AI 可调用的工具函数的 docstring 会变成 AI 看到的工具说明所以 docstring 一定要写清楚参数含义mcp.run()— 启动服务默认走 stdio 协议Claude Desktop 用的就是 stdio踩坑提醒docstring 里一定要写清楚每个参数是什么、留空代表什么。AI 是根据 docstring 决定怎么调用的写不清楚 AI 会乱传参。第 4 步测试 Server 能不能跑uv run python server.py如果没报错说明启动成功。它会停在那里等输入——这是正常的因为 MCP Server 是常驻服务。三、接入 Claude Desktop1 分钟Claude Desktop 的配置文件在这两个位置之一系统路径macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.json打开没有就新建加入你的 MCP Server{mcpServers:{sqlite-demo:{command:uv,args:[run,--directory,/绝对路径/mcp-sqlite-demo,python,server.py]}}}踩坑提醒--directory后面必须是绝对路径相对路径会导致 Claude Desktop 找不到项目。Windows 路径用双反斜杠\\或正斜杠/。保存后完全退出 Claude Desktop 再重开不是最小化是右键退出。四、实测效果打开 Claude Desktop输入查一下张三的所有订单你会看到 Claude 自动调用了query_orders工具参数传了customer张三返回结果。再试帮我统计一下订单整体情况Claude 会调用get_order_stats直接给你汇总数据。这就是 MCP 的价值你不用写 SQL不用切窗口AI 直接查你的库。五、3 个常见踩坑坑 1Claude Desktop 里看不到工具原因配置文件 JSON 格式错了或者路径不对。排查Claude Desktop 菜单栏 → Developer → Logs看错误日志。最常见的报错是command not found或ENOENT。解决把uv换成完整路径比如C:\\Users\\你\\AppData\\Roaming\\Python\\Scripts\\uv.exe。坑 2AI 调用了工具但报错 “no such table”原因SQLite 数据库路径是相对路径Claude Desktop 的工作目录不是你的项目目录。解决DB_PATH用绝对路径或者在server.py开头加importos os.chdir(os.path.dirname(os.path.abspath(__file__)))坑 3工具能调但 AI 不主动用原因docstring 写得太简单AI 不知道什么时候该用这个工具。解决docstring 里加一句使用场景提示比如查询订单列表。当用户问查订单某客户的订单订单情况时调用此工具。六、从 Demo 到生产3 个进阶方向这个 Demo 只是入门。真实项目里你可以接 MySQL/PostgreSQL— 把sqlite3换成pymysql或psycopg工具函数逻辑不变加写操作工具— 写一个create_order工具让 AI 能帮你录数据。注意加上权限校验避免 AI 误删接 REST API— 写一个call_api工具让 AI 能查外部接口。比如接天气 API、汇率 API完整代码我放在了 [GitHub 仓库地址]包含以上 3 个进阶版本。写在最后这篇教程目标很简单让你亲手跑通一个 MCP Server真正理解 AI 是怎么连上本地数据库的。你拿到的是一份可直接复用的代码server.py是工具函数的核心写法init_db.py是测试数据生成方式claude_desktop_config.json是 MCP 客户端接入模板建议你现在就复制代码跑一遍把 SQLite 换成自己的业务库只需要改 SQL 和 DB 连接方式。如果你在跟练过程中遇到报错直接评论区贴出来我会优先回复具体报错信息。MCP 现在还在早期生态远没有 Cursor 插件那么成熟但这也意味着先学会的人能占住工具链的位置。学到这一步你已经比大多数只会用 AI 聊天的开发者更进一步。觉得有用就点个关注后面继续写我踩过坑的实战内容。本文参与 CSDN「MCP 协议开发实战」征文如果对你有帮助点个赞支持一下