企业官网建设流程全解析

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

本文参与 CSDN「MCP 协议开发实战」征文活动
标签：#MCP #Model Context Protocol #Claude Desktop #AI Agent

前言：为什么你该现在学 MCP

如果你用过 Claude Desktop、Cursor、或者 Cline，大概率遇到过这个场景：

AI 说"我无法访问你的数据库/文件/API，请把内容贴给我"。

MCP（Model Context Protocol）就是解决这个问题的。它让 AI 能直接调用你本地的工具——查数据库、读文件、调 API——不用你手动复制粘贴。

Anthropic 2024 年底开源了这套协议，到 2026 年中，Cursor、Cline、Claude Desktop、Windsurf 都已经原生支持。学会写一个 MCP Server，等于给你的 AI 装上了手。

这篇我带你从 0 搭一个能查 SQLite 数据库的 MCP Server，接进 Claude Desktop，全程不超过 5 分钟。代码可以直接复用到你自己的项目里。

一、环境准备（1 分钟）

你需要装好这三样：

为什么用uv而不是pip：MCP 官方 SDK 用uv管理依赖更快，且uv run能自动创建虚拟环境，省去手动venv的步骤。

检查环境：

python--version# 应该 >= 3.10uv--version# 应该有输出

二、5 分钟搭一个能查 SQLite 的 MCP Server

第 1 步：初始化项目

mkdirmcp-sqlite-demo&&cdmcp-sqlite-demo uv init uvadd"mcp[cli]"sqlite3

mcp[cli]是官方 Python SDK，sqlite3是 Python 内置库（实际上不用单独装，这里写上是为了 uv 识别）。

第 2 步：准备一个测试数据库

先建一个简单的 SQLite 库，放点测试数据：

# init_db.pyimportsqlite3 conn=sqlite3.connect("demo.db")c=conn.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 mcp=FastMCP("sqlite-demo")DB_PATH="demo.db"@mcp.tool()defquery_orders(customer:str="",status:str="")->str:"""查询订单列表。 Args: customer: 客户姓名，留空查全部 status: 订单状态（已支付/已发货/退款中/待发货），留空查全部 Returns: JSON 格式的订单列表字符串 """conn=sqlite3.connect(DB_PATH)c=conn.cursor()sql="SELECT id, customer, amount, status, created_at FROM orders WHERE 1=1"params=[]ifcustomer:sql+=" AND customer = ?"params.append(customer)ifstatus:sql+=" AND status = ?"params.append(status)rows=c.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: 统计摘要字符串 """conn=sqlite3.connect(DB_PATH)c=conn.cursor()total=c.execute("SELECT COUNT(*), SUM(amount) FROM orders").fetchone()by_status=c.execute("SELECT status, COUNT(*) FROM orders GROUP BY status").fetchall()conn.close()summary=f"总订单数：{total[0]}，总金额：¥{total[1]:.2f}\n"summary+="状态分布：\n"fors,ninby_status:summary+=f" -{s}：{n}单\n"returnsummaryif__name__=="__main__":mcp.run()

代码解读（3 个关键点）：

1. FastMCP("sqlite-demo")— 创建一个 MCP Server，名字随便取
2. @mcp.tool()装饰器 — 把普通 Python 函数变成 AI 可调用的工具，函数的 docstring 会变成 AI 看到的工具说明，所以 docstring 一定要写清楚参数含义
3. mcp.run()— 启动服务，默认走 stdio 协议（Claude Desktop 用的就是 stdio）

踩坑提醒：docstring 里一定要写清楚每个参数是什么、留空代表什么。AI 是根据 docstring 决定怎么调用的，写不清楚 AI 会乱传参。

第 4 步：测试 Server 能不能跑

uv run python server.py

如果没报错，说明启动成功。它会停在那里等输入——这是正常的，因为 MCP Server 是常驻服务。

三、接入 Claude Desktop（1 分钟）

Claude Desktop 的配置文件在这两个位置之一：

打开（没有就新建），加入你的 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 个常见踩坑

坑 1：Claude Desktop 里看不到工具

原因：配置文件 JSON 格式错了，或者路径不对。

排查：Claude Desktop 菜单栏 → Developer → Logs，看错误日志。最常见的报错是command not found或ENOENT。

解决：把uv换成完整路径，比如C:\\Users\\你\\AppData\\Roaming\\Python\\Scripts\\uv.exe。

坑 2：AI 调用了工具但报错 “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 只是入门。真实项目里你可以：

1. 接 MySQL/PostgreSQL— 把sqlite3换成pymysql或psycopg，工具函数逻辑不变
2. 加写操作工具— 写一个create_order工具，让 AI 能帮你录数据。注意加上权限校验，避免 AI 误删
3. 接 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 协议开发实战」征文，如果对你有帮助，点个赞支持一下 👍