从零手写MCP服务：让AI真正操作你的数据库和本地工具

做 AI 提效这几年，我最怕听到的一句话就是：“vibe coding 不就是让 AI 写代码嘛。”说这话的人，多半是看了一堆短视频 demo，以为打开聊天窗口喊一句“帮我做个网站”，剩下就全交给魔法了。真上过手的人都知道，AI 聊得再嗨，只要碰不到你的数据库、接口、设计稿或本地环境，它就只是个“嘴强王者”。真正把 vibe coding 从玩具变成生产力的，是 MCP。

MCP，全称 Model Context Protocol，模型上下文协议。它给 AI 客户端提供了一种统一接入外部工具的方式。你可以把它理解成 AI 世界的 USB 接口：手机电脑都有 USB 口，你插上硬盘能存文件，插上摄像头能录视频，插上手柄能打游戏。MCP 就是这个“口”，你通过它把数据库、浏览器、设计工具、服务器脚本一个个“插”到 AI 身上。

今天我准备手把手把一个完整的 MCP 服务从零写出来。不是讲概念，而是直接把代码跑起来、把配置填好、把客户端连上去、把坑踩一遍。读完这篇文章，你应该能复刻出一个稳定运行的本地任务管家 MCP，并且搞清楚它背后那些“为什么”。不管你用的是 Claude Desktop、Cursor、Codex 还是 Cherry Studio，这套流程都能迁移。

先说重点：本文所有代码都基于本地环境，不需要额外申请云服务，跟着敲就行。项目不复杂，但足以帮你建立对 MCP 服务开发的完整心智模型。

1. vibe coding 跑不通，大多数问题出在“没有工具”

1.1 “自然语言生成代码”其实只解决了前半段

vibe coding 这个词最初指的是用自然语言描述需求，让 AI 连续生成和修改代码的编码方式。听起来很随意，但一个容易被忽略的事实是：AI 的“爽点”在于它能快速产出草稿，而“痛点”是它永远无法自动验证自己是不是真的把事情做对了。

举个例子。你让 AI 写一个统计报表接口，它能瞬间生成一大堆代码。但当你问它“这个接口连的数据库里有几条订单”时，它就沉默了。为什么？因为它手上没有数据库连接。哪怕你把表结构贴给它，它也只能“猜”着写，而不是“用”着写。这样生成出来的代码，很多只能在理想条件下运行，一碰到真实数据就崩。

所以 vibe coding 的正确定义不是“让 AI 随便写”，而是让 AI 处在有反馈、有工具、有执行路径的闭环里。这个闭环就是：AI 调用外部工具 → 工具执行完成 → 返回结构化结果 → AI 根据结果调整下一步。你越早意识到这一点，越不容易被 demo 带偏。

1.2 MCP 就是给 AI 装上传感器和机械臂

如果你用过浏览器自动化或者命令行工具，你会发现很多 MCP 服务本质上就是“已有的工具，加一层协议包装”。

比如你想让 AI 查数据库，可以给它一个“执行 SQL 并返回结果”的工具；你想让 AI 读取网页，可以给它一个“抓取 URL 并转成 Markdown”的工具；你想让 AI 操作设计稿，可以接一个 Figma 或蓝湖的服务。每一个工具都像一个小插件，AI 自己决定什么时候调用。

MCP 协议规定了三件事：

• 客户端怎么发现服务器提供的工具列表；
• 客户端怎么把你的指令转成标准请求发给工具；
• 工具执行完之后怎么把结果带回来。

只要服务器实现了这套协议，任何支持 MCP 的客户端都能直接用。不需要每个客户端各自发明一套“插件 API”。这也是 2025 年以来，Cursor、Claude、Codex、Cherry Studio、Cline 等十几个主流工具都支持 MCP 的根本原因。

1.3 为什么“自己写一个 MCP 服务”是最高效的学习路径

网上现成的 MCP 服务器非常多，有连接 GitHub 的、有连接数据库的、有连接设计稿的。直接安装当然可以，但如果你完全没写过服务器，一旦遇到“AI 找不到工具”“连接不上”“配置不生效”，你根本不知道是客户端问题、协议问题还是工具本身的问题。

手写一个小服务，你会彻底搞懂这几个关键点：

• MCP 服务端如何暴露“工具”；
• 工具的参数和返回值为什么必须设计得极其严谨；
• stdio 和 HTTP/SSE 两种模式有什么区别；
• 客户端配置文件的路径和格式是怎么工作的。

这些东西只有亲手跑一遍才能形成肌肉记忆。所以我建议所有人都从零手写一次，哪怕最后你的正式项目只是复用别人的 MCP，这段基础也不会白学。

2. 先别急着写代码：这四件事决定后面不返工

2.1 选 stdio 还是 HTTP/SSE：先看客户端在哪台机器

MCP 服务器有两种主流通信方式。第一种是 stdio，客户端启动一个本地子进程，双方通过标准输入输出传递 JSON 消息。第二种是 HTTP/SSE（也包含较新的 Streamable HTTP），服务器作为常驻服务，客户端通过网络请求访问。

怎么选？我的经验很简单：如果 AI 客户端和 MCP 服务跑在同一台电脑上，优先选 stdio。它的好处是部署成本为零，没有端口、没有 CORS、没有认证，更安全，因为你不需要把一个服务暴露到网络上。Claude Desktop、Cursor、Codex 这些本机工具，日常跟本地 MCP 打交道基本都是 stdio。

如果你有多个客户端、多台机器要同时连同一个服务，或者服务部署在服务器上给团队用，那就要考虑 HTTP/SSE 或者 Streamable HTTP。这时候你得多考虑几个问题：鉴权怎么做、日志怎么收、进程怎么守护。建议不要一上来就上分布式架构，先把 stdio 跑通再谈网络化。

2.2 开发语言与 SDK：Python 和 TypeScript 是主流

MCP 官方提供了 Python SDK 和 TypeScript SDK，写作本文时还有 Java、Go、C# 等社区实现。我这里选择 Python，原因是 Python 生态里自带了很多数据处理和系统管理库，写本地工具非常顺手；另外它的类型提示配上 MCP 的 schema 生成非常舒服。

有一个重要的设计点：MCP 工具的参数定义，不是你在代码里写多少就暴露多少。SDK 会通过类型提示和函数签名自动生成 JSON Schema，然后发给客户端。也就是说，你定义函数时参数命名和注释写得越清楚，AI 能理解和使用得越准确。很多人写的 MCP 工具看起来能用但表现很傻，问题往往出在参数说明太敷衍。

如果你对 Node 更熟，用 TypeScript 也完全没问题，官方 SDK 风格类似。Java 那边 Solon AI 和 Spring Boot 都有 MCP 集成方案，但主要用于企业级服务，这里不展开。

2.3 客户端配置文件其实是统一的“套路”

不同的客户端有不同的配置文件位置和名字，但核心结构大同小异。只要你把 MCP 服务器命令配好，客户端启动时会自动拉起这个进程。我给几个常见客户端的印象路径，帮助你先有个全局认识：

配置文件里最核心的字段就是命令和参数。例如本地 Python 脚本启动，一般写：

json复制{
  "mcpServers": {
    "vibe-task-server": {
      "command": "python",
      "args": ["/绝对路径/vibe_task_server.py"]
    }
  }
}

注意 command 最好写绝对路径或确认已在 PATH 中，否则在图形化客户端里经常出现“找不到 python”的问题。

2.4 先查生态再决定是否自己造轮子

写代码前，我也建议你先搜一下要接的东西有没有现成 MCP。现在官方和社区生态已经很丰富了：数据库有 MySQL、PostgreSQL、SQLite 的 MCP 服务，浏览器有 Playwright 的 MCP，游戏引擎有 Unity、Unreal 甚至 Cocos Creator 的 MCP，安全工具有 x64dbg、Burp Suite 的 MCP，数据分析工具有 MATLAB 的 MCP，设计工具有 Figma 和蓝湖的 MCP。

如果只是把 A 工具的数据暴露给 AI，直接用现成服务是最省事的。那什么时候才需要自己写？我总结了三类情况：一是业务逻辑很特殊，通用服务包不住；二是你希望 AI 不只读取数据，还能调用你内部的函数或脚本；三是为了学习协议本身，练手和架构验证。接下来这个项目，正好是第二类和第三类的结合。

3. 手把手写一个本地任务管家 MCP 服务

3.1 三步搭好项目骨架

我先带你做一个“vibe task server”，核心功能是让 AI 能帮你创建任务、查询任务、完成任务。任务数据存在本地 SQLite 里。这个例子覆盖了 MCP 最常见的能力：写数据、读数据、参数校验、返回值结构化。

第一步，创建目录和虚拟环境：

bash复制mkdir vibe-task-server
cd vibe-task-server
python -m venv .venv
source .venv/bin/activate

第二步，安装 MCP SDK：

bash复制pip install "mcp[cli]"

如果你在中国大陆网络环境，建议把 pip 源换成镜像，这个属于常规操作，大家应该都很熟。装完以后可以跑一下 python -c "import mcp; print(mcp.__file__)" 确认 SDK 正常。[cli] 会额外装一个 inspector 工具，后面联调用得上。

第三步，新建一个 server.py。为了减少模块耦合，我这个服务只有 120 行左右的代码，不拆多文件，方便你直接复制学习。

3.2 核心代码：工具定义和 SQLite 落地

下面这个代码文件有两个 main 部分：一部分初始化 SQLite，另一部分把操作封装成 MCP 工具。

python复制import sqlite3
from datetime import datetime
from pathlib import Path
import json

from mcp.server.fastmcp import FastMCP

DB_PATH = Path.home() / "vibe_task.db"
mcp = FastMCP("vibe-task-server")

def get_conn():
    conn = sqlite3.connect(DB_PATH)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS tasks (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            title TEXT NOT NULL,
            status TEXT NOT NULL DEFAULT 'todo',
            note TEXT,
            created_at TEXT
        )
    """)
    return conn

@mcp.tool()
def create_task(title: str, note: str = "") -> str:
    """创建一条新的任务记录。

    Args:
        title: 任务标题，一句话说清楚要做什么。
        note: 任务的补充说明，没有可以为空字符串。

    Returns:
        JSON 字符串，包含新任务的 id、title、status、created_at。
    """
    conn = get_conn()
    now = datetime.now().isoformat(timespec="seconds")
    cur = conn.execute(
        "INSERT INTO tasks (title, status, note, created_at) VALUES (?, 'todo', ?, ?)",
        (title, note, now),
    )
    conn.commit()
    task_id = cur.lastrowid
    conn.close()
    return json.dumps({
        "id": task_id,
        "title": title,
        "status": "todo",
        "created_at": now,
    }, ensure_ascii=False)

@mcp.tool()
def list_tasks(status: str = "") -> str:
    """查询当前任务列表，支持按状态过滤。

    Args:
        status: 可选，传入 todo / done 时只返回对应状态的任务；不传则返回全部。

    Returns:
        JSON 数组字符串，每个任务包含 id、title、status、note、created_at。
    """
    conn = get_conn()
    if status:
        rows = conn.execute(
            "SELECT id, title, status, note, created_at FROM tasks WHERE status = ? ORDER BY id DESC",
            (status,),
        ).fetchall()
    else:
        rows = conn.execute(
            "SELECT id, title, status, note, created_at FROM tasks ORDER BY id DESC"
        ).fetchall()
    conn.close()
    result = [
        {
            "id": r[0],
            "title": r[1],
            "status": r[2],
            "note": r[3],
            "created_at": r[4],
        }
        for r in rows
    ]
    return json.dumps(result, ensure_ascii=False)

@mcp.tool()
def complete_task(task_id: int) -> str:
    """将某条任务标记为已完成。

    Args:
        task_id: 任务的数字 ID。

    Returns:
        JSON 字符串，包含被更新任务的 id 和最新状态。
    """
    conn = get_conn()
    cur = conn.execute(
        "UPDATE tasks SET status = 'done' WHERE id = ?",
        (task_id,),
    )
    conn.commit()
    affected = cur.rowcount
    conn.close()
    if affected == 0:
        return json.dumps({"error": f"task {task_id} not found"}, ensure_ascii=False)
    return json.dumps({"id": task_id, "status": "done"}, ensure_ascii=False)

if __name__ == "__main__":
    mcp.run(transport="stdio")

代码逻辑本身不难，我提醒几个细节。

mcp = FastMCP("vibe-task-server") 里的名字会在客户端工具列表里显示成 vibe-task-server_create_task 这种带前缀的形式。如果你把一个工具叫做 create_task，多个服务同时接入时不会撞名，这是 MCP 的默认命名空间机制。

create_task 的返回是 JSON 字符串，不是普通自然语言。为什么？因为工具的返回值要作为上下文回填给模型。如果返回的是“插入成功”四个字，模型只知道成功了，不知道新生成的 ID；如果返回一段格式混乱的字符串，模型的后续理解也会变差。JSON 是人和机器都容易理解的“最小公约数”。

3.3 参数设计为什么要“长这样”

你仔细看代码里每个函数都写了 Args。这个不是给人看的文档，是给模型当“使用说明”的。MCP 客户端请求模型时会把这个函数的签名、描述、参数约束一起发给模型。模型会根据这些信息判断“我需要调用哪个工具、传什么参数”。

写工具描述有个铁律：要写“这个工具能做什么、适合在什么场景下用”，不要只写一堆形容词。举两个例子对比：

• 差劲的描述：删除任务
• 好的描述：根据任务 ID 把任务标记为已完成。适合在用户明确说“搞定/完成/关掉某任务”时调用。删除后状态不可恢复，调用前如果 ID 无法确认，先 list_tasks 查询。

第二个描述包含了触发条件和注意事项，模型在真实场景里会更准确地触发。这是 MCP 工具从“能跑”到“好用”的关键差距。

我的代码里还有个小设计：complete_task 更新不到记录时返回 JSON 的 error 字段，而不是直接抛异常。原因在于，MCP 工具如果抛异常，客户端通常会显示“工具调用失败”，但模型并不知道具体失败原因。返回 JSON 能保留更多信息，让模型自己决定下一步，比如告诉用户“找不到这条任务，是不是 ID 输错了”。

3.4 本机联调：先用 Inspector，再接到 Claude Desktop

代码写完以后，先别急着开客户端，用官方调试工具看一眼。

如果你的 MCP SDK 带 cli，可以这样启动 Inspector：

bash复制mcp dev server.py

这个命令会拉起本地调试面板。我看面板里能看到暴露的工具列表、参数 Schema，还能直接手动传参调用。这一步能隔离“工具本身的问题”和“客户端接入的问题”。如果你在 Inspector 里调用一切正常，那基本可以确定服务端没问题。

冒烟测试没问题以后，我习惯用 Claude Desktop 或 Cherry Studio 做真实客户端验证。以 Claude Desktop 为例，配置文件里加这一段：

json复制{
  "mcpServers": {
    "vibe-task-server": {
      "command": "python",
      "args": ["/绝对路径/vibe-task-server/server.py"]
    }
  }
}

Windows 用户如果 python 命令不是系统 PATH 里的，建议写全路径：

json复制{
  "mcpServers": {
    "vibe-task-server": {
      "command": "C:\\Users\\你的用户名\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["D:\\projects\\vibe-task-server\\server.py"]
    }
  }
}

保存后完全退出客户端再重启，然后去工具管理页面查看连接状态。正常情况下你会看到 vibe-task-server 以及下面三个工具。

此时你可以跟 AI 说一句：“帮我创建一条任务，标题是调研 MCP 文档，备注明天上午前完成。”如果配置正确，几秒后它会调用 create_task，你再用 SQLite 命令行查一下 vibe_task.db，就能看到数据已经写进数据库。这一瞬间你会对 vibe coding 有完全不同的理解——AI 不再是给你编代码，而是真的在操作你的本地系统。

4. 让 vibe coding 工作流真正好用的三个细节

4.1 description 写得好，工具调用准确率提升一大截

很多人把 MCP 服务做好以后，发现 AI 不按预期调用。我排查过不少类似问题，最后发现一半以上是 description 太短或语气模棱两可。

模型读工具描述，跟我们人类做选择题一样。它需要明确的“边界条件”。比如，一个工具接收 url 参数来抓取网页内容，那描述里最好明确写上支持哪些协议、会返回什么格式、失败时可能有什么原因。这样模型知道什么时候用它，而不是在客户端里乱试。

另外参数名本身也很重要。我见过有人把任务标题的参数命名为 a，把备注命名为 b。SDK 能正常生成 schema，但模型看到 a、b 根本不知道含义，只能从 description 里猜。最后调用率很差。所以参数命名要像写公共 API 一样清晰：task_title、comment、status，别偷懒。

4.2 工具返回结果尽量结构化，别给模型“倒垃圾”

工具的返回值会完整进入模型的上下文窗口。如果你的工具把一张 2000 行的数据表全返回出来，模型很可能被无关字段淹没，甚至触发上下文超长。正确做法是服务端先做预处理，把模型需要的核心信息提炼出来。

比如，查询任务列表，如果只想让 AI 知道“最近 5 条未完成任务”，可以直接在 SQL 里加 LIMIT 5，让工具返回摘要。把截断、聚合、过滤放到工具端做，而不是让模型自己消化原始数据。这就像你给同事交代任务时只说重点，不会把几十页日志原封不动丢给他。

如果你的工具本身数据非常大，还可以考虑分页参数，让模型每次只取一页。加上一个 limit 参数，语义明确，调用方也能控制成本。

4.3 从 Claude Desktop 扩展到 Cursor、Codex 和 Cherry Studio

同样的 MCP 服务对接 Cursor，通常是在项目根目录的 .cursor/mcp.json 里写一样的 JSON。Cursor 的界面会在 MCP 区域显示工具名，你可以直接让 AI 写代码过程中调用本地任务工具。

Codex 是 OpenAI 的命令行客户端。新版支持通过 codex mcp add 添加服务器，老版本则需要在 config.toml 里写 [mcp_servers.xxx] 配置。建议你安装后先用 codex mcp --help 看当前支持的命令，再按格式写入，因为版本迭代很快，写死的老命令可能在最新版已经变了。

Cherry Studio 这种带图形界面的客户端更简单，直接在设置里找到 MCP 管理，填一个名字、命令和参数就行，通常界面上还会实时显示连接日志。核心 JSON 结构与 Claude Desktop 没有本质区别，你只要理解“MCP 客户端会拉起服务器进程”这个动作，所有工具配置都是相通的。

这里有一个重要提醒：每改一次配置，客户端必须完全重启才生效。不要在客户端开着的时候修改 mcp.json，然后期望立刻生效。绝大多数“为什么没反应”都是这个原因。

5. 经典翻车现场：从热门 MCP 话题看避坑姿势

5.1 配置没问题但 AI 说找不到工具

这个问题在社区提问里非常高频：“MCP 服务明明显示连接成功，为什么 AI 说没有这个工具？”我总结出三个排查方向：

第一，客户端是否重启。改了配置后，很多客户端只在启动时加载 MCP 列表，运行期间新加的工具不会被识别。第二，服务端是否报错退出。stdio 模式下，如果 Python 脚本启动瞬间就崩溃，客户端会显示连接失败或工具列表为空。你可以在终端手动执行一次同样的命令，看看有没有异常堆栈。第三，日志是否污染了标准输出。

这个问题我单独强调一下。stdio 模式中，客户端和服务器通过 stdout 交换 JSON 消息。如果代码里用 print("hello") 或者在调试时把 logging.StreamHandler() 绑到 stdout，就会往协议通道里混入非 JSON 内容，导致通信解析失败。所有日志请输出到 stderr，或者直接写文件。排查时也可以把 MCP 服务的日志关到最小，只留错误信息，这样最干净。

5.2 “现成 MCP 一大堆，还要不要自己写”

这个问题的答案取决于你的需求边界。如果你只是想给 Claude 接个 MySQL 查询，用社区维护的 MySQL MCP 就行，自己在 .cursor/mcp.json 里写好数据库连接信息，一分钟就能用。没有必要因为“学习”就去重写一个数据库驱动。

但如果你发现现成服务始终无法满足需求，比如它不支持你的数据库类型、每次返回格式太乱、或者调用链里需要穿你自己的鉴权逻辑，那自己写就是正路。自己写 MCP 的价值在于，你能精确控制“AI 看到什么工具、拿到什么返回”。这个控制力，是任何通用工具都给不了的。

我个人的习惯是：先花 10 分钟搜索开源市场，如果能找到 star 高、维护积极的现成服务，先试；试不通，并且你能看到它的源码，那就 fork 改一版；如果连源码都看不懂或根本没人维护，再考虑自己从零写。别迷信“自己写才是高手”，能用好现有工具本身就是效率。

5.3 MCP、Skill/Agent 和 Prompt 到底是什么关系

随着 vscode、Codex、Cline 这些客户端不断更新，“Skill”、“Agent”这些概念都冒出来了，很多人容易混。在我理解里，它们解决的是不同层面的问题：

Prompt 是“话术”，告诉模型怎么回答问题。Skill 一般是一组预先定义好的元能力或工作流，比如“先规划再写代码”“每步都运行测试”，它指导模型的行为模式。而 MCP 是“外接工具”，解决的是模型能调用什么、能操作什么的问题。

你可以这样理解：Prompt 决定了 AI 的“性格”，Skill 决定了 AI 的“习惯”，MCP 决定了 AI 的“手和脚”。三者互相配合，不是替代关系。所以在选型时，不要把 MCP 和 Skill 对立起来，而应该想清楚自己缺的是哪一层。

5.4 Figma、蓝湖、Unity、MySQL……生态型 MCP 为何经常“掉链子”

生态型 MCP 是社区里最热闹的话题。搜一下热搜就能看到：Figma MCP、蓝湖 MCP、Cocos Creator MCP、Unity MCP、MATLAB MCP、Wazuh MCP、x64dbg MCP 等等。这些工具能大大扩展 AI 的能力边界，但它们也是最容易出现“工具注册不上”的重灾区。

原因在于，这类 MCP 服务很多是个人维护或小团队维护的，它们对特定平台的版本要求非常敏感。比如某个设计工具改了 API 返回结构，MCP 服务没跟上，就会表现为“连接正常，但任何请求都报鉴权错误”。再比如某个游戏引擎的 MCP，需要你先安装特定插件和 token，一旦漏了某个环境变量，AI 就找不到对应工具。
把 Figma MCP 接进 Codex 这类工具时，大家常碰到的“工具注册不上”，我建议按这个顺序排查：

1. 确认你的开发 token 是否有效，以及 token 是否有对应文档访问权限；
2. 确认 MCP 服务启动时读的环境变量是否真正被客户端透传了；
3. 用 Inspector 或命令行直接调一次服务看报错；
4. 如果服务走的是 HTTP/SSE，确认端口可以访问、地址没写错、防火墙没拦。

数据库类 MCP 的掉链子通常是另一个故事。以 MySQL MCP 为例，很多版本要求在环境变量或启动参数里写好账号、密码、主机和端口。如果你的客户端是图形应用，在 macOS 上启动时不一定继承你终端里的环境变量。这时候把敏感信息直接写进 args 或 env 配置，反而更稳定，但也意味着你要注意配置文件本身的安全性，别把含密码的 json 提交到 git 里。

5.5 给 MCP 服务做一点防御：超时、状态和可观测性

MCP 服务虽然只是本地工具，但它被 AI 调用以后，行为是动态的。你不能保证模型每次传的参数都合理。我建议在工具内部保留基本的错误处理，至少要返回“参数不合法”的结构化信息，而不是让异常裸奔到客户端。

除此以外，日志记录是另一个容易忽略的环节。stdio 模式里日志不要打 stdout，但也不能完全不记录。我在生产习惯里会把日志写入本地文件，记录每次调用时间、传入参数、返回摘要。这样万一哪天 AI 干出奇怪的事，你有据可查。你也可以把本地数据库多备份几份，防止 AI 误删除数据。MCP 给你带来自动化的便利，但前提是你愿意为它做好护栏。

做一个 MCP 服务并不是很难，难的是你要像对待正式接口一样对待工具函数：参数语义清晰，返回结构稳定，异常分支完整。把它定位成“给 AI 使用的 API”，一切设计都有了解法。

如果你只是想体验 vibe coding，接下来可以把我这个任务管家接进日常使用的客户端，试着让 AI 每天上班记录待办、下班汇总完成情况。等你跑顺了，再把里面的 SQLite 换成你自己业务的数据库，把工具函数替换成内部系统的操作，你就会发现,vibe coding 真正打开方式的精髓不是“AI 多有想象力”，而是你现在可以控制“AI 能做什么”。