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

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 分钟）

你需要装好这三样：

工具	版本要求	安装命令
Python	3.10+	官网下载，或 pyenv install 3.11
uv	最新版	pip install uv
Claude Desktop	任意版本	官网下载

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

检查环境：

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

---

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

第 1 步：初始化项目

mkdir mcp-sqlite-demo && cd mcp-sqlite-demo
uv init
uv add "mcp[cli]" sqlite3

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

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

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

# init_db.py
import sqlite3

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.py
from mcp.server.fastmcp import FastMCP
import sqlite3

mcp = FastMCP("sqlite-demo")

DB_PATH = "demo.db"

@mcp.tool()
def query_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 = []
    if customer:
        sql += " AND customer = ?"
        params.append(customer)
    if status:
        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]}
        for r in rows
    ]
    return str(result)


@mcp.tool()
def get_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"
    for s, n in by_status:
        summary += f"  - {s}：{n} 单\n"
    return summary


if __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 的配置文件在这两个位置之一：

系统	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%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 个常见踩坑

坑 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 开头加：

import os
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 协议开发实战」征文，如果对你有帮助，点个赞支持一下 👍