乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > MCP 入门:给 AI 插上工具的翅膀

MCP 入门:给 AI 插上工具的翅膀

当前时间： 2026-05-01 00:43:43 更新时间： 2026-05-01 分类：软件教程 评论(0)

MCP 入门:给 AI 插上工具的翅膀

不知道你有没有遇到过这种情况：用豆包、Kimi 或 Trae 这类 AI 工具时，想让 AI 帮你查个天气、读个文件、或者查数据库，但它只能”纸上谈兵”，给你一堆建议，却无法真正动手去做。

MCP（Model Context Protocol）就是为了解决这个问题而生的。

开始之前

在动手之前，你需要确认以下几点：

•Python 3.10 或更高版本已安装•uv 已安装（Python 包管理工具，比 pip 更快更现代）——安装方式：curl -LsSf https://astral.sh/uv/install.sh | sh•Node.js 已安装（用于运行 MCP Inspector 调试工具）•基础的 Python 异步编程概念（async/await）•了解 LLM（大语言模型）的基本使用方式

MCP 是什么

MCP 是 Anthropic 在 2024 年 11 月推出的一个开放协议。简单来说，它像是一个”USB-C 接口”，让 AI 模型可以标准化地连接各种外部工具和数据源。

没有 MCP 之前，每个 AI 应用想连接外部工具，都得自己写一套对接代码。M 个应用 × N 个工具，就是 M×N 种对接方式，维护成本极高。

有了 MCP 之后，只要你的工具实现了 MCP 协议，任何支持 MCP 的 AI 应用都能直接调用它。一次开发，到处使用。

核心架构

MCP 的架构很简单，主要由三部分组成：

•Host（宿主）：你使用的 AI 应用，比如 Trae、Cursor、OpenCode•Client（客户端）：Host 内置的 MCP 客户端，负责和 Server 通信•Server（服务器）：你开发的 MCP 服务，暴露工具、资源等功能

它们之间的关系是：你通过 Host 和 AI 对话，AI 需要调用外部工具时，Client 会转发请求给 Server，Server 执行完把结果返回来，AI 再整理成自然语言告诉你。

快速上手：用 Python 写一个 MCP Server

我们用 Python 来写一个简单的 MCP Server，实现一个查询天气的工具。

先用 uv 创建项目并安装依赖：

uv init mcp-weathercd mcp-weatheruv add "mcp[cli]" httpx

然后创建 weather_server.py：

import loggingfrom mcp.server.fastmcp import FastMCPimport httpxmcp = FastMCP("weather-server")API_BASE = "https://wttr.in"logger = logging.getLogger(__name__)@mcp.tool()async def get_weather(city: str) -> str:    """查询指定城市的天气"""    async with httpx.AsyncClient() as client:        resp = await client.get(f"{API_BASE}/{city}?format=3")        return resp.textif __name__ == "__main__":    logger.info("Weather server is running... transport=stdio, ctrl+c to stop.")    mcp.run(transport="stdio")

就这么几行代码，一个 MCP Server 就完成了。@mcp.tool() 装饰器会自动把函数注册为可被 AI 调用的工具，Python 的类型提示和 docstring 会被自动转换成工具的描述和参数定义。

运行它：

uv run weather_server.py

用 MCP Inspector 调试

Server 写好了，怎么验证它是否正常工作？MCP 官方提供了一个调试工具——MCP Inspector。

启动 Inspector 连接你的 Server：

npx @modelcontextprotocol/inspector uv run weather_server.py

运行后会在浏览器中打开一个调试界面。你可以在里面：

•查看你的 Server 暴露了哪些工具•手动调用工具并查看返回结果•查看底层的 JSON-RPC 通信消息

调试时我发现 Inspector 特别有用：刚写好的工具，不确定参数对不对，直接在 Inspector 里试一下就能看到完整的输入输出，比盲猜效率高得多。

如果 get_weather 没有出现, 点一下 List Tools

传输模式

MCP 支持两种传输模式：

•stdio：本地模式，通过标准输入输出通信，适合本机使用•Streamable HTTP：远程模式，通过 HTTP + SSE 通信，适合部署到服务器

开发时用 stdio 最简单，需要远程访问时可以切换到 HTTP 模式：

if __name__ == "__main__":    # mcp.run(transport="stdio") # transport="stdio"是默认值    mcp.run(transport="streamable-http")

如果你的 Server 使用 HTTP 传输模式，如上边的代码, 运行

uv run weather_server.py

然后在另一个终端运行下边的命令, 出现的Web调试界面如上边的差不多

npx @modelcontextprotocol/inspector --server-url http://127.0.0.1:8000/mcp

三种核心能力

MCP Server 可以提供三种类型的能力：

1. Tools（工具）

工具是 AI 可以调用的函数，用于执行操作或获取数据。就像刚才的天气查询例子。

工具可以有参数，参数通过 Python 函数签名自动定义：

@mcp.tool()async def search_products(keyword: str, limit: int = 10) -> str:    """搜索商品    Args:        keyword: 搜索关键词        limit: 返回数量限制    """    # 你的搜索逻辑    return f"找到 {limit} 个与 '{keyword}' 相关的商品"

2. Resources（资源）

资源是只读的数据，类似于 REST API 中的 GET 接口。AI 可以读取资源但不能修改它。

@mcp.resource("config://app")def get_config() -> str:    """获取应用配置"""    return '{"theme": "dark", "language": "zh"}'@mcp.resource("file://docs/{name}")def read_doc(name: str) -> str:    """读取文档"""    return f"文档 {name} 的内容..."

3. Prompts（提示词模板）

提示词模板是可复用的交互模式，帮助用户快速完成特定任务。

@mcp.prompt()def code_review(code: str) -> str:    """代码审查提示词"""    return f"请审查以下代码，指出潜在问题和改进建议：\n\n{code}"

在 AI 应用中使用

开发完 Server 后，你需要把它配置到 AI 应用中。不同应用的配置方式类似，这里以 OpenCode 为例。

OpenCode（终端 AI 工具）

OpenCode 是一个开源的终端 AI 工具，也支持 MCP。编辑 OpenCode 的配置文件添加 MCP Server。

配置文件在~/.config/opencode/opencode.json (全局) 或你的本地项目根目录下的/opencode.json

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "weather-server": {      "enabled": true,      "type": "remote",      "url": "http://127.0.0.1:8000/mcp"    },    "weather-local": {      "enabled": true,      "type": "local",      "command": [        "uv",        "--directory",        "/your/project/path/mcp-weather",        "run",        "weather_server.py"      ]    }  }}

mcp 下的weather-server与weather-local只要二选一就可以了, 如果选择weather-server, 记得要把http运行起来。 配置完成后，在 OpenCode 中直接对话，AI 就能调用你的天气查询工具了。配置一次，多个支持 MCP 的应用都能用。

常见的坑

刚接触 MCP 时，有几个容易踩的坑：

  • 不要用 print() 调试 stdio 模式的 Server。stdio 模式下，stdout 用于 MCP 协议通信，print() 会破坏通信。用 print(..., file=sys.stderr) 或 logging 模块代替。这也是为什么建议用 MCP Inspector 来调试。

  • 工具永远返回字符串

  • 参数必须加类型注解

  • 不要抛异常，返回错误信息字符串

总结

MCP 让 AI 不再只是”会说话”，而是真正能”动手做事”。用 Python 开发 MCP Server 门槛很低，几行代码就能让 AI 调用你的工具。

写好 Server 后，先用 MCP Inspector 调试确认正常，再配置到 AI 应用中使用。这个流程走通一次，后面开发新的 Server 就很顺畅了。

如果你平时用 Trae、OpenCode 这类支持 MCP 的 AI 工具，不妨试试用 MCP 把自己常用的功能封装起来。一次开发，以后在任何支持 MCP 的应用里都能直接用，效率提升很明显。