当下大模型的能力边界正在不断拓展，但原生大模型普遍存在无法直连外部网络、难以调用第三方接口的短板。想要让AI实现查天气、查快递、读取本地文件等实用功能，传统方案需要为每一个外部工具单独编写适配代码，耦合度高、后期维护难度大。而MCP（模型上下文协议） 的出现，完美解决了这一痛点，它作为一套标准化通信协议，充当起大模型与外部工具之间的通用桥梁，实现工具与AI模型的解耦，让工具开发、集成、扩展变得简单高效。

本文将以天气查询工具为落地案例，基于轻量的FastMCP框架，一步步完成MCP服务开发、主流编辑器集成、AI Agent调用全流程实操。全程代码可直接运行，零基础开发者也能跟着搭建属于自己的首个MCP应用。

一、读懂MCP：AI工具调用的标准化解决方案

1.1 什么是MCP

MCP全称模型上下文协议，你可以将它理解为AI生态的通用转接接口。它制定了统一的通信规则，不管是第三方API、本地脚本、数据库还是文件服务，只要按照MCP规范封装成服务，各类大模型、AI编辑器、智能Agent都能无缝调用，无需重复开发适配逻辑。

我们通过两个场景直观感受它的价值：

1. AI编辑器场景：在Cursor这类AI编程编辑器中，原生AI无法联网查询天气。接入MCP天气服务后，编辑器AI可自动调用工具获取天气数据，甚至将结果写入代码注释，全程无需手动操作接口。
2. 智能Agent场景：自主开发的问答Agent想要叠加天气、快递查询等功能时，只需将对应能力封装为MCP工具，Agent即可自动识别调用，新增或修改工具不会改动Agent核心代码。

1.2 MCP核心优势

对比传统点对点对接方式，MCP的核心优势十分突出：

• 标准化通信：统一请求与返回格式，一套工具可适配多款大模型与AI应用，告别重复适配；
• 低耦合易扩展：工具逻辑与AI主体完全分离，新增、迭代工具互不影响主程序运行；
• 多传输兼容：支持Stdio、WebSocket等主流传输方式，本地调试用Stdio，远程部署可切换WebSocket；
• 轻量易落地：依托FastMCP这类轻量化框架，仅需基础Python语法就能开发MCP服务，部署零门槛。

本次实战选用FastMCP框架，该框架对Python极度友好，仅需少量代码就能将普通Python函数转化为标准MCP工具，大幅降低入门难度。

二、前期准备：环境与密钥配置

正式开发前，我们需要完成虚拟环境搭建、依赖包安装，同时准备第三方接口密钥。本次案例选用高德地图天气API作为数据源。

2.1 搭建Python虚拟环境（推荐）

使用虚拟环境可以避免不同项目的依赖包版本冲突，执行以下命令创建并激活环境：

# 创建名为mcp-env的虚拟环境
python3 -m venv mcp-env

# macOS/Linux 激活虚拟环境
source mcp-env/bin/activate

# Windows 激活虚拟环境
mcp-env\Scripts\activate

2.2 安装项目依赖

一次性安装MCP框架、网络请求、大模型对接等所需依赖库：

pip3 install requests fastmcp pydantic langchain langchain-openai langchain-mcp-adapters langgraph

2.3 获取高德地图API Key

1. 访问高德开放平台并完成账号注册；
2. 进入控制台创建应用，选择Web服务类型；
3. 生成专属API Key，妥善保存，后续代码中会用到。

三、核心开发：编写天气查询MCP服务

这是本次实战的核心环节，我们将编写MCP服务主文件，封装高德天气接口，完成工具注册、参数校验、异常捕获等全套逻辑。

3.1 编写MCP服务代码

新建文件 weather_mcp.py，该文件即为独立运行的MCP服务端，完整代码如下：

import requests
from typing import Annotated
from mcp.server.fastmcp import FastMCP
from pydantic import Field

# 初始化FastMCP服务实例
mcp_server = FastMCP()

# 注册MCP工具：定义工具名称、功能描述、入参规则
@mcp_server.tool(
    name="query_city_weather",
    description="查询国内地级市的实时天气信息，支持温度、天气状况、风向风力、空气湿度查询"
)
def query_city_weather(
    city: Annotated[str, Field(
        description="需要查询的城市中文全称",
        examples=["北京", "上海", "广州", "成都"]
    )]
) -> str:
    """对接高德地图天气API，标准化返回天气数据"""
    # 替换为你自己的高德地图API Key
    AMAP_API_KEY = "你的高德API Key"
    # 高德天气基础接口地址
    api_url = f"https://restapi.amap.com/v3/weather/weatherInfo?city={city}&key={AMAP_API_KEY}&extensions=base"

    try:
        # 发起网络请求，设置10秒超时防止服务阻塞
        response = requests.get(api_url, timeout=10)
        response.raise_for_status()
        result_data = response.json()

        # 校验接口返回状态，判断是否查询成功
        if result_data.get("status") != "1" or not result_data.get("lives"):
            return f"查询失败：暂不支持{city}，或接口请求异常"

        # 解析实时天气数据
        weather_info = result_data["lives"][0]
        # 格式化输出结果，提升可读性
        return (
            f"【{weather_info['city']} 实时天气】\n"
            f"当前温度：{weather_info['temperature']}℃\n"
            f"天气状况：{weather_info['weather']}\n"
            f"风向风力：{weather_info['winddirection']}风 {weather_info['windpower']}级\n"
            f"空气湿度：{weather_info['humidity']}%"
        )

    except requests.exceptions.Timeout:
        return "查询失败：网络请求超时，请稍后重试"
    except Exception as e:
        return f"查询失败：程序异常，错误信息：{str(e)}"

if __name__ == "__main__":
    # 启动MCP服务，采用Stdio传输协议（本地集成首选）
    mcp_server.run(transport="stdio")

3.2 代码核心逻辑解析

1. 工具注册：通过 @mcp_server.tool 装饰器完成工具注册，名称和描述会被大模型识别，用于判断何时调用该工具；
2. 参数约束：借助Annotated和Field注解规范入参，明确参数含义与示例，减少大模型传参错误；
3. 异常防护：针对网络超时、接口报错、未知异常做分层处理，保证MCP服务稳定运行；
4. 传输协议：选用stdio协议，无需占用额外端口，是本地对接编辑器、Agent的最优选择。

3.3 本地启动测试

在虚拟环境中执行以下命令启动MCP服务：

python weather_mcp.py

终端无报错即代表服务启动成功，此时服务处于监听状态，等待客户端调用。

四、实战集成一：对接Cursor编辑器

Cursor是主流的AI编程编辑器，原生兼容MCP协议，我们只需简单配置，就能让编辑器内的AI自动调用天气查询工具。

4.1 配置MCP服务接入

1. 打开Cursor编辑器，使用快捷键唤起命令面板：
   • macOS：Cmd + Shift + P
   • Windows：Ctrl + Shift + P
2. 输入 MCP: Open Settings，打开MCP配置文件；
3. 在 mcpServers 节点下添加自定义服务配置，务必填写weather_mcp.py的绝对路径：

{
  "mcpServers": {
    "weather_mcp_service": {
      "type": "stdio",
      "command": "python3",
      "args": ["/你的本地绝对路径/weather_mcp.py"]
    }
  }
}

适配提示：Windows系统需将command改为python，同时保证Python已添加到系统环境变量中。

4.2 功能验证

保存配置后，Cursor会自动加载MCP服务。在编辑器的AI对话窗口输入自然语言指令，例如：帮我查一下北京今天的天气。

此时Cursor内置AI会自动识别并调用我们开发的query_city_weather工具，返回格式化的天气数据，无需任何手动干预。你也可以尝试让AI将天气结果写入代码注释，体验完整联动效果。

五、实战集成二：对接LangChain Agent

除了编辑器，MCP还能无缝对接AI Agent开发框架。下面我们基于LangChain+LangGraph搭建智能Agent，实现自然语言理解+自动调用MCP工具的完整流程。

5.1 编写Agent调用代码

新建文件 agent_run.py，代码实现Agent连接MCP服务、解析指令、调用天气工具的逻辑：

import asyncio
import os
import uuid

from langchain_core.messages import HumanMessage
from langchain_core.runnables import RunnableConfig
from langchain_mcp_adapters.sessions import StdioConnection
from langgraph.prebuilt import create_react_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_mcp_adapters.client import MultiServerMCPClient
from pydantic import SecretStr

# 初始化大模型（示例使用豆包大模型，可替换为任意兼容OpenAI接口的模型）
llm = ChatOpenAI(
    base_url="https://api.302.ai/v1",
    api_key=SecretStr(os.getenv("DASHSCOPE_API_KEY")),
    model="Doubao-1.5-lite-32k",
    timeout=None,
)

# 配置Agent系统提示词，定义角色与应答规范
system_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是智能生活助手，可调用外部工具查询天气，回答简洁、信息准确。"),
    ("human", "{messages}"),
])

async def connect_mcp_and_run_agent():
    # 配置本地MCP服务连接信息
    async def load_mcp_tools():
        mcp_config = {
            "weather_server": StdioConnection(
                transport="stdio",
                command="python3",
                args=["/你的本地绝对路径/weather_mcp.py"],
                encoding="utf-8",
            )
        }
        # 创建MCP客户端并加载工具
        mcp_client = MultiServerMCPClient(mcp_config)
        return await mcp_client.get_tools()

    # 加载MCP工具列表
    mcp_tools = await load_mcp_tools()
    # 创建ReAct类型智能Agent
    agent = create_react_agent(model=llm, prompt=system_prompt, tools=mcp_tools)

    # 发起查询请求
    response = await agent.ainvoke(
        input=HumanMessage(content="今天上海天气怎么样？出门需要注意什么？"),
        config=RunnableConfig(configurable={"session_id": str(uuid.uuid4())})
    )
    # 打印最终回复
    print("Agent回复：\n", response["messages"][-1].content)

if __name__ == '__main__':
    # 运行异步Agent任务
    asyncio.run(connect_mcp_and_run_agent())

5.2 运行与调试要点

1. 密钥安全：将大模型API密钥配置到系统环境变量，禁止在代码中硬编码密钥；
2. 路径校验：再次确认代码中weather_mcp.py的绝对路径无误；
3. 启动运行：直接执行 python agent_run.py，Agent会自动拉起MCP服务、调用天气工具，并结合天气数据给出综合回答。

六、MCP开发与集成避坑指南

结合本次实战，整理开发和集成过程中的高频问题，帮助大家少走弯路：

1. 密钥安全第一：高德API Key、大模型密钥等敏感信息，统一通过环境变量或配置文件读取，杜绝明文硬编码；
2. 路径优先使用绝对路径：Cursor、LangChain对接MCP服务时，相对路径极易导致加载失败，全程使用文件绝对路径；
3. 区分传输协议：本地调试、编辑器对接使用stdio协议；若需对外提供远程MCP服务，可切换为WebSocket协议；
4. 优化工具描述：工具名称、功能描述、参数说明要精准清晰，大模型依赖描述判断调用时机，描述模糊会导致调用失效；
5. 完善异常逻辑：网络请求、接口调用务必增加超时、异常捕获，避免单个工具崩溃导致整个AI应用宕机。

七、拓展与总结

7.1 功能拓展方向

本文的天气查询只是MCP的入门案例，基于这套架构，你可以快速拓展更多实用工具：

• 接口类：快递查询、股价查询、新闻资讯等第三方API封装；
• 本地服务类：本地文件读写、脚本执行、数据库查询等；
• 办公类：文档解析、表格数据处理等工具。

所有拓展工具的开发逻辑与天气工具完全一致，只需替换核心业务代码即可。

7.2 总结

MCP作为大模型工具调用的标准化协议，正在成为AI Agent、AI编辑器的基础能力。它彻底打破了大模型与外部资源的壁垒，将模型决策和工具执行彻底解耦，让开发者专注于业务功能本身，而非繁琐的接口适配。

通过本次实战，我们完成了从MCP理论理解、服务开发，到编辑器、AI Agent双场景集成的全流程操作。掌握这套开发模式后，你可以轻松搭建多样化的MCP工具集，持续拓展大模型的落地能力，打造功能更强大的智能AI应用。