前言

Model Context Protocol（简称 MCP）是目前 AI Agent 生态中最重要的工具协议之一。

MCP 的核心逻辑非常简单：

AI Client
   │
   │ JSON-RPC (stdio)
   ▼
MCP Server
   │
   ▼
本地工具 / 数据库 / API

也就是说：

• AI 客户端（Client）
• 通过 标准输入输出（stdio）
• 与 MCP Server 进行 JSON-RPC 通信

当你打开
Claude Desktop
或其他支持 MCP 的客户端时，它们会：

1. 读取配置文件
2. 自动执行

python main.py

3. 将你的脚本作为 AI 可调用的工具服务器

本教程将带你构建一个：

能被 AI 自动调用的 SQLite 数据查询 MCP Server

简单来说就是一个 “数据库导盲犬”。

AI 不需要 SQL，就能查询你的本地数据库。

环境与硬件配置

验证 Python：

python --version

如果返回类似：

Python 3.11.6

说明环境正常。

如果提示：

python 不是内部或外部命令

需要重新安装 Python 并勾选：

Add Python to PATH

步骤 1：创建 MCP 工作目录

建议集中管理所有 MCP Server，不要散落在用户目录。

推荐目录结构：

C:\MCP_Servers\
   └─ sql_server\
        ├─ venv
        └─ main.py

创建目录：

mkdir C:\MCP_Servers\sql_server
cd C:\MCP_Servers\sql_server

创建 Python 虚拟环境：

python -m venv venv

激活虚拟环境：

.\venv\Scripts\activate

成功后终端会出现：

(venv) C:\MCP_Servers\sql_server>

安装依赖：

pip install mcp[cli] sqlalchemy

说明：

确认安装：

pip list

应该能看到：

mcp
sqlalchemy

步骤 2：编写 MCP Server 核心逻辑

创建文件：

main.py

完整示例代码：

from mcp.server.fastmcp import FastMCP

# 创建一个名为 LocalData 的 MCP Server
mcp = FastMCP("LocalData")


@mcp.tool()
def read_project_status(project_name: str) -> str:
    """
    查询本地项目进度
    AI 会根据用户提问自动调用该函数
    """

    db_mock = {
        "clawreach": "进度 85%，正在调试 WebSocket",
        "shizi": "项目已上线"
    }

    return db_mock.get(project_name.lower(), "未找到该项目")


if __name__ == "__main__":
    # 启动 MCP Server
    # 默认使用 stdio 传输模式
    mcp.run()

MCP Server 运行原理

很多人第一次会疑惑：

为什么没有端口？

原因是 MCP 默认使用：

stdio transport

通信方式：

Claude Desktop
      │
      │ stdin/stdout
      ▼
python main.py
      │
      ▼
工具函数

优点：

步骤 3：在客户端注册 Server（关键）

客户端必须知道：

1️⃣ 用哪个 Python
2️⃣ 运行哪个脚本

找到配置文件：

%APPDATA%\Claude\claude_desktop_config.json

完整路径通常是：

C:\Users\你的用户名\AppData\Roaming\Claude\

如果文件不存在，可以手动创建。

示例配置：

{
  "mcpServers": {
    "my_sql_helper": {
      "command": "C:/MCP_Servers/sql_server/venv/Scripts/python.exe",
      "args": [
        "C:/MCP_Servers/sql_server/main.py"
      ],
      "env": {
        "MY_DB_PATH": "C:/data/shizi.db"
      }
    }
  }
}

字段说明：

注意：

必须使用：

绝对路径

否则客户端无法启动。

步骤 4：验证 Server 是否成功启动

完成配置后：

1️⃣ 完全退出 Claude Desktop
2️⃣ 重新启动客户端

成功标志：

聊天界面右下角会出现：

🔨 工具图标

点击后可以看到：

my_sql_helper
 └ read_project_status

这说明：

AI 已经成功识别你的 MCP Server。

测试 MCP Server

可以在对话框输入：

查询 clawreach 项目的最新进度

Claude 会自动调用：

read_project_status("clawreach")

返回：

进度 85%，正在调试 WebSocket

整个过程：

用户问题
   │
Claude
   │
自动选择工具
   │
调用 MCP Server
   │
返回结果

避坑指南（非常重要）

1 路径转义问题

JSON 中路径必须使用：

推荐写法：

C:/path/to/file

或：

C:\\path\\to\\file

不要写：

C:\path\to\file

否则会解析错误。

2 必须使用 venv 的 Python

错误写法：

command: python

正确写法：

C:/MCP_Servers/sql_server/venv/Scripts/python.exe

原因：

客户端启动时不会继承你的 shell 环境。

3 Server 无法启动

建议直接手动运行：

python main.py

如果程序报错，先解决 Python 依赖问题。

4 MCP 工具没有显示

排查顺序：

1️⃣ 配置文件 JSON 是否正确
2️⃣ Python 路径是否存在
3️⃣ 脚本路径是否正确
4️⃣ Claude 是否完全重启

进阶：真正接入 SQLite

如果你想连接真实数据库，可以这样写：

import sqlite3

def get_conn():
    return sqlite3.connect("data.db")

然后在工具函数里执行 SQL。

AI 就可以：

• 查询订单
• 查询日志
• 查询用户数据

总结

完成本教程后，你已经掌握了 MCP 的核心能力：

✔ 创建 MCP Server
✔ 暴露 AI 工具函数
✔ 通过 stdio 与 AI 通信
✔ 在 Claude Desktop 挂载插件

这意味着：

你的 AI 已经可以：

访问数据库
调用本地工具
控制自动化脚本

也就是 真正的 AI Agent 工具系统。