MCP

一、先搞懂：MCP不是高深技术，是AI的“万能连接器”

咱们先抛掉官方定义（Model Context Protocol，模型上下文协议），用一个生活化的例子类比：

你有一部手机（相当于我们常用的AI，比如Claude、GPT），手机本身很强大，但它不能直接用U盘、鼠标、耳机——除非有一个“充电口”（也就是接口）。以前的手机接口五花八门，有的是Micro-USB，有的是Type-C，换个设备就用不了；而MCP，就相当于给所有AI统一了一个“Type-C接口”，不管你用的是哪款AI，不管你想连接电脑文件、本地笔记，还是服务器、硬件，只要通过这个接口，就能“即插即用”。

简单说：MCP的核心作用，就是让AI能轻松访问我们本地的东西、调用各种工具，而且不用反复适配，一次连接，所有AI都能用。

二、小白最关心：没有MCP，AI会“束手无策”？

很多人可能会说，我平时用AI写文案、查资料，不用MCP也好好的啊？那是因为你用的是AI的“基础功能”，如果想让AI帮你做更贴合自己的事，没有MCP就会很麻烦。

举两个最常见的场景，一看就懂：

❌ 没有MCP的困扰：你想让AI帮你整理电脑里的本地Excel台账（没上传到网上），AI会告诉你“对不起，我无法访问你的本地文件”；你想让AI帮你查自己电脑里的笔记，它也做不到——因为AI和你的本地文件“断联”了，没有一个统一的通道能让它们沟通。

✅ 有了MCP的便捷：只要装一个简单的MCP“连接器”（不用懂复杂代码，跟着教程点几下就行），AI就能直接读取你电脑里的Excel、PDF、笔记，甚至能帮你运行电脑里的命令、查看日志，相当于给AI开了一个“本地权限”，让它成为你的专属助手。

三、再通俗点：MCP就是“AI的本地通行证”

我们可以把整个过程想象成：

AI是一个很聪明的“外援”，但它被关在“网络世界”里，进不来你的电脑（本地设备）；而MCP，就是给这个外援办了一张“本地通行证”，还配了一个“翻译官”——让AI能看懂你电脑里的文件、能调用你电脑里的工具，也能把它的指令传递给你的设备。

而且这张“通行证”是“通用的”，不管你换哪个AI（Claude、Cursor还是其他AI工具），只要有这张通行证，都能自由进出你的本地设备，不用再给每个AI单独办“通行证”（也就是不用反复适配各种接口）。

四、MCP底层架构

核心三角色：

① MCP Client（客户端）：相当于“AI的接头人”，装在AI工具里（比如Claude、Cursor），负责和MCP Server沟通，传递AI的指令（比如“帮我读一下本地Excel”），再把结果回传给AI。

技术逻辑：客户端内置 MCP 协议解析模块，支持 STDIO（本地直连）、HTTP/SSE（远程连接）两种传输方式，无需用户手动开发，只需配置连接参数（如服务端路径、传输方式），即可与本地服务端建立双向通信，将 AI 的自然语言指令转化为服务端可识别的标准化指令（如调用read_local_file工具并传入文件路径）。

② MCP Server（服务端）：相当于“本地设备的守门人”，装在你的电脑/服务器上，负责接收AI的指令，调用本地能力（比如读取文件、运行命令），再把结果反馈给Client。

技术逻辑：基于 Python 异步 IO（async/await）实现，通过Server类初始化服务实例，用@app.tool()装饰器注册本地工具（如文件读取、命令执行），工具函数需定义标准化参数（如文件路径、命令内容）和返回格式，确保客户端可识别；启动服务后，默认通过 STDIO 或 HTTP/SSE 监听请求，接收客户端指令并调用本地能力。

对应实操：代码中app = Server("my-file-server")初始化服务，read_local_file函数注册为工具，app.run()启动监听，本质就是服务端的核心实现。

③ 传输层：相当于“Client和Server之间的通道”，负责传递数据，不用自己搭建，MCP默认提供两种简单方式，按需选择即可。

技术逻辑：MCP 默认使用 JSON 格式封装数据（指令类型、工具名称、参数、返回结果），无需用户手动处理序列化 / 反序列化；STDIO 传输通过本地进程间通信（无网络依赖），HTTP/SSE 通过 TCP 端口传输，两种方式均内置错误处理（如连接中断重连、指令解析失败反馈），保障数据传输稳定。

两种传输方式（入门者优先选第一种）：

① STDIO（本地直连）：最常用、最安全，不用开端口，相当于AI和电脑“直接对话”，数据全程在本地，不经过外网，适合个人使用（比如用AI读本地文件）。

② HTTP/SSE（远程连接）：适合多设备共享，比如同一局域网内的多台电脑，都能通过这个通道连接同一个MCP Server，适合小团队使用。

（以 “AI 读取本地文件” 为例）

服务端部署：用户通过 Python 代码启动 MCP Server，注册 “本地文件读取” 工具，服务端进入监听状态；
客户端连接：AI 工具（如 Cursor）的 MCP Client 配置连接参数（选择 STDIO 传输），与本地服务端建立连接；
指令传递：用户向 AI 发送指令（“读取本地笔记.md”），AI 通过 Client 将指令转化为标准化请求（指定工具read_local_file、参数path），传递给服务端；
本地执行：服务端解析请求，调用注册的工具函数，执行本地文件读取操作，获取文件内容；
结果反馈：服务端将执行结果（文件内容）封装为标准化响应，通过传输层返回给 Client，Client 再将结果传递给 AI，AI 整理后反馈给用户。

总结：底层逻辑就是“AI→Client→传输层→Server→本地设备”，再反向返回结果，流程很简单，入门者不用写代码，也能理解整个数据传递过程。

关键技术点

工具注册机制：通过装饰器@app.tool()实现，本质是将本地函数（如文件读取、命令执行）注册到服务端的工具列表，AI 可通过 MCP 协议自动识别工具的功能、参数，无需手动适配；
异步通信：服务端基于异步 IO 实现，可同时处理多个客户端请求（如同时读取多个文件、执行多个命令），避免阻塞；
跨系统兼容：通过platform模块判断系统（Windows/Mac/Linux），适配不同系统的本地调用逻辑（如 Windows 用 CMD、Mac 用 bash 执行命令），这也是代码中兼容多系统的核心。

五、MCP应用场景

不用觉得MCP是程序员的专属，普通人、入门技术者都能用到它的核心功能，除了之前分享的基础场景，补充4个更实用的拓展场景，兼顾易用性和技术入门需求，每个场景均附完整代码教程，可直接复制运行：

本地文件问答（纯小白也能⽤）：不用把PDF、Word、笔记上传到网上（担心隐私泄露），通过MCP，AI能直接读取你电脑里的文件，帮你总结重点、提炼内容，比如你存了一堆工作笔记，让AI帮你整理成汇报，不用自己逐字看。
AI辅助写代码（入门技术者重点）：如果你是新手学编程，用Cursor、VSCode的AI插件，通过MCP，AI能直接读取你电脑里的项目代码，帮你找bug、补代码，甚至帮你运行调试，不用再手动复制粘贴代码给AI；进阶一点，还能让AI调用本地编译器，实时查看代码运行结果。
办公自动化（小白/入门者通用）：让AI帮你整理电脑里的Excel数据、自动生成报表，甚至帮你调用本地邮件工具发邮件，省去大量重复操作，比如每月要统计的台账，AI通过MCP读取Excel，几分钟就能整理好；入门技术者还能简单配置，让AI定时执行这些操作（比如每天自动整理前一天的文件）。
局域网/小型服务器管理（入门技术者适用）：如果家里有树莓派、小型服务器，通过MCP Server部署在服务器上，AI能远程调用服务器的命令，查看进程、监控日志，甚至简单控制硬件（比如控制树莓派连接的灯光），不用手动登录服务器操作，新手也能轻松上手。

六、使用步骤(基础仅方便理解)

所有教程均基于Python环境（最通用，新手易操作），先完成基础环境搭建，再对应学习具体应用场景，代码可直接复制，每一行均有详细注释，不用懂复杂编程逻辑，跟着步骤走就能成功运行。

前置准备：基础环境搭建

不管哪个应用场景，都需要先完成这2步，全程5分钟搞定：

安装Python（已安装的跳过）：

去Python官网（https://www.python.org/）下载对应系统版本（Windows/Mac），安装时务必勾选“Add Python to PATH”（添加到环境变量），安装完成后，打开CMD（Windows）/终端（Mac），输入“python –version”，能显示版本号即安装成功。

安装MCP SDK（核心工具）：

在CMD/终端输入以下命令，复制粘贴即可，等待1-2分钟安装完成：

pip install mcp  # 核心MCP SDK，所有场景都需要
pip install openpyxl  # 读取Excel文件必备（办公自动化场景用）
pip install python-dotenv  # 配置环境（服务器管理场景用）

应用教程1：本地文件读取

场景：让AI读取本地TXT、Markdown文件，总结内容、提取重点，不用上传文件，保护隐私。

步骤1：编写MCP Server代码（可直接复制）

新建一个文本文件，复制下面代码，保存为“mcp_file_server.py”（保存路径建议放在桌面，方便操作）：

# 导入MCP核心模块
from mcp.server import Server
from mcp.types import Tool

# 1. 初始化MCP服务，名称可随便起（比如my-file-server）
app = Server("my-file-server")

# 2. 注册“读取本地文件”的工具（AI会自动识别这个工具）
@app.tool()  # 装饰器，告诉MCP这是一个可被AI调用的工具
async def read_local_file(path: str) -> str:
    """
    读取本地文件的工具（AI会看到这个注释，知道该怎么用）
    :param path: 文件的完整路径（比如C:\Users\XXX\Desktop\笔记.txt）
    :return: 文件的内容（返回给AI，供AI分析）
    """
    try:
        # 打开文件，读取内容（encoding="utf-8"避免中文乱码）
        with open(path, "r", encoding="utf-8") as f:
            content = f.read()
        return f"文件读取成功，内容如下：\n{content}"
    except Exception as e:
        # 捕获异常（比如路径错误、文件不存在），返回错误信息，避免服务崩溃
        return f"文件读取失败，原因：{str(e)}"

# 3. 启动MCP服务（启动后，AI才能连接）
if __name__ == "__main__":
    print("MCP文件服务启动中...")
    app.run()  # 启动服务，默认使用STDIO传输方式（本地直连）

步骤2：启动MCP Server

打开CMD/终端，输入“cd 桌面”（切换到文件保存路径，若保存在其他路径，替换为对应路径）；
输入“python mcp_file_server.py”，看到“MCP文件服务启动中…”即启动成功，不要关闭这个CMD/终端（关闭则服务停止）。

步骤3：AI客户端对接+使用

打开支持MCP的AI工具（推荐Claude桌面端、Cursor）；
找到“MCP连接”选项，选择“本地连接”，传输方式默认“stdio”，点击“连接”，提示“连接成功”；
在AI对话框输入指令（替换成自己的文件路径）：

“帮我读取本地路径为【C:\Users\XXX\Desktop\工作笔记.md】的文件，总结里面的核心重点，分点说明”

AI会通过MCP调用本地服务，读取文件并返回总结，全程无文件上传，隐私可控。

注意：文件路径务必写对（Windows用反斜杠\，Mac用正斜杠/），不会找路径就右键文件→“属性”→“位置”，复制粘贴即可。

应用教程2：办公自动化（读取Excel，入门技术者适用）

场景：让AI读取本地Excel文件，统计数据、生成报表，省去手动整理的麻烦，适合职场人、学生。

步骤1：编写MCP Server代码（可直接复制）

新建文本文件，复制下面代码，保存为“mcp_excel_server.py”：

# 导入所需模块（MCP核心+Excel读取模块）
from mcp.server import Server
from mcp.types import Tool
from openpyxl import load_workbook  # 读取Excel的模块（已提前安装）

# 初始化MCP服务
app = Server("my-excel-server")

# 注册“读取Excel并统计数据”的工具
@app.tool()
async def read_excel_and_analysis(path: str, sheet_name: str = "Sheet1") -> str:
    """
    读取本地Excel文件，统计数据并简单分析（AI会识别这个工具的用法）
    :param path: Excel文件的完整路径（比如C:\Users\XXX\Desktop\月度台账.xlsx）
    :param sheet_name: Excel的工作表名称，默认是Sheet1（可根据自己的Excel修改）
    :return: 数据统计结果（返回给AI，供AI进一步整理）
    """
    try:
        # 加载Excel文件
        workbook = load_workbook(path)
        # 选择工作表
        sheet = workbook[sheet_name]
        # 获取Excel的总行数、总列数
        row_count = sheet.max_row
        col_count = sheet.max_column
        # 获取表头（第一行数据）
        headers = [cell.value for cell in sheet[1]]
        # 获取前10行数据（避免数据过多，可根据需求修改）
        data = []
        for row in range(2, min(row_count + 1, 11)):
            row_data = [cell.value for cell in sheet[row]]
            data.append(dict(zip(headers, row_data)))
        # 关闭Excel文件
        workbook.close()
        # 返回统计结果
        return f"Excel读取成功！\n工作表：{sheet_name}\n总行数：{row_count}\n总列数：{col_count}\n表头：{headers}\n前10行数据：{data}\n请帮我统计数据并生成简洁报表（分点说明）"
    except Exception as e:
        return f"Excel读取失败，原因：{str(e)}"

# 启动服务
if __name__ == "__main__":
    print("MCP Excel服务启动中...")
    app.run()

步骤2：启动服务+对接AI

打开CMD/终端，切换到文件保存路径（比如“cd 桌面”）；
输入“python mcp_excel_server.py”，启动服务（不要关闭CMD/终端）；
AI客户端对接MCP服务（和教程1步骤3一致，连接成功即可）。

步骤3：使用AI整理Excel数据

在AI对话框输入指令（替换成自己的Excel路径和工作表名称）：

“帮我读取本地路径为【C:\Users\XXX\Desktop\2026年4月台账.xlsx】的Excel文件，工作表名称是【销售数据】，统计每个产品的销售额，生成简洁报表，标注最高销售额和最低销售额”

AI会调用MCP服务读取Excel数据，自动统计并生成报表，全程不用手动复制粘贴数据。

补充：常见问题排查

启动服务时提示“no module named ‘mcp’”：说明MCP SDK没安装成功，重新在CMD/终端输入“pip install mcp”，确保安装完成。
AI连接失败：检查MCP服务是否启动（CMD/终端是否处于运行状态），传输方式是否选择“stdio”，路径是否正确。
读取文件/Excel失败：检查文件路径是否正确，文件是否存在，Excel文件是否处于打开状态（关闭Excel再尝试）。
命令执行失败：检查命令是否符合自己的系统（Windows和Mac/Linux命令不同），避免执行高危命令。

七、Codex、Claude、Cursor 集成 MCP 的技术实现

三款工具均原生支持 MCP 协议，集成逻辑一致（客户端集成 + 连接配置），差异仅在于客户端适配细节和功能侧重，具体如下：

1. Cursor（代码编辑专用 AI）集成实现

聚焦 “编辑器与本地项目联动”，MCP 客户端集成在编辑器内核中，与代码编辑功能深度绑定；

内置 MCP Client 模块，默认支持 STDIO 传输（无需配置端口），启动后自动检测本地运行的 MCP Server；
客户端与编辑器文件管理模块联动，可直接获取当前打开的项目路径，通过 MCP 调用服务端工具，实现 “代码读取、调试、运行” 一站式操作；
适配逻辑：用户打开本地项目后，Cursor 的 MCP Client 自动关联项目路径，AI 指令（如 “查错”“补全”）通过 MCP 传递给服务端，服务端读取项目文件并返回结果，实时同步到编辑器界面。

ps：仅支持与 “当前打开的本地项目” 联动，未打开项目时无法通过 MCP 读取本地文件，本质是客户端对项目路径的关联限制。

2. Claude（通用 AI）集成实现

聚焦 “多场景本地资源调用”，MCP 客户端集成在桌面端（网页端暂不支持），侧重灵活交互；

客户端支持 STDIO、HTTP/SSE 两种传输方式，可自动检测本地 MCP Server，无需手动输入服务端路径；
内置指令解析模块，可将复杂自然语言指令（如 “批量读取 Python 文件并生成文档”）转化为标准化 MCP 请求，调用服务端多个工具（文件读取、命令执行）；
权限控制：默认不限制命令执行权限，需用户在服务端代码中添加高危命令拦截（如前文代码中可新增if command in ["rm", "del"]判断），避免风险。

3. Codex（代码生成专用 AI）集成实现

聚焦 “适配本地环境的代码生成”，MCP 客户端集成在客户端 / VS Code 插件中，侧重环境适配；

客户端支持手动配置服务端路径（HTTP/SSE 传输），或自动关联 STDIO 传输的本地服务端；
与本地环境检测模块联动，通过 MCP 调用服务端执行pip list（查看依赖）、python --version（查看版本）等命令，获取本地环境信息，生成适配的代码；
支持与本地版本控制工具（如 Git）联动，通过 MCP 调用 Git 命令，实现 “版本状态查看、提交” 等操作，与代码生成功能深度融合。

ps：客户端需确保本地编译器路径已添加到环境变量，否则通过 MCP 调用编译器运行代码时会报错，本质是客户端对本地环境的依赖适配。

PREVIOUSGitHub上利用CI/CD自动化部署上线静态网页

NEXTUni-app 项目如何用 GitHub CI/CD 自动部署到 GitHub Pages：完整 SOP、底层原理与避坑总结

MCP