【AI技术_工具】用 MCP 把本地工具接入 Claude_Cursor，让 AI 真正摸到你的数据-平芜编程栈

前言

你有没有遇到过这种场景：你让 Claude 帮你分析一份本地的 CSV 销售数据，或者读取某个目录下的日志文件，结果它一脸无辜地说"我无法访问你的文件"？

问题不在于 Claude 不够聪明，而在于它缺少"手"。大型语言模型默认是纯文本接口，看不到你本地的文件、数据库、API。而MCP（Model Context Protocol，模型上下文协议）正是为了解决这个问题而生的标准协议——它让 AI 客户端（如 Claude Desktop、Cursor、VS Code）通过统一的协议调用你本地的工具和服务。

今天这篇博客，我带你从零搭建一个 MCP 服务器，把你的本地文件系统变成一个 AI 可以直接"摸"到的数据源。

一、MCP 到底是什么？大白话解释

你可以把 MCP 理解成AI 和外部世界之间的"翻译官"。

传统模式下，AI 只有一个聊天窗口，你能发的只有文字。有了 MCP 之后，AI 可以：

读取你的本地文件（日志、配置、数据库）
调用你写的 Python 脚本
连接外部 API（天气、股票、Jira 等）

MCP 的核心架构只有三个角色：

角色	职责	举例
Host（客户端）	发起请求，转发给 LLM	Claude Desktop、Cursor、VS Code
MCP Server（服务端）	提供工具和能力	你写的文件读取服务器
LLM（大模型）	理解用户意图，调用工具	Claude 3.5 Sonnet

当你在 Cursor 里问"帮我看看昨天的错误日志"，MCP 的工作流程如下：

你 → Cursor(Cursor) → MCP Server(读取文件) → 返回日志内容 → Claude 分析 → 返回答案

全程对用户透明，就像 AI 天生就有这个能力。

二、环境准备

MCP 推荐使用 Python 生态的mcp库，安装非常简单：

# 创建专用虚拟环境（推荐）python3-mvenv ~/mcp-tutorial-venvsource~/mcp-tutorial-venv/bin/activate# 安装 MCP SDKpipinstall"mcp[cli]"

验证安装成功：

mcp--version

确保你的 MCP Host（比如 Claude Desktop）也支持 MCP。目前 Claude Desktop、Cursor、VS Code 原生支持 MCP Server 配置。

三、实操步骤：搭建你的第一个 MCP 文件读取服务器

我们写一个 MCP Server，让 AI 能读取指定目录下的所有 Markdown 文件。

步骤 1：创建服务器代码

新建文件~/mcp-tutorial/file_read_server.py：

frommcp.server.fastmcpimportFastMCPfrompathlibimportPath# 初始化 MCP 服务器mcp=FastMCP("LocalFileReader",description="读取本地目录下的 Markdown 文件")# 定义第一个工具：读取单个文件@mcp.tool()defread_markdown_file(filepath:str)->str:"""读取指定的 Markdown 文件内容"""try:path=Path(filepath)ifnotpath.exists():returnf"❌ 文件不存在:{filepath}"ifnotpath.suffix==".md":returnf"❌ 只支持 .md 文件，当前后缀:{path.suffix}"returnpath.read_text(encoding="utf-8")exceptExceptionase:returnf"❌ 读取失败:{e}"# 定义第二个工具：列出目录下所有 md 文件@mcp.tool()deflist_markdown_files(directory:str)->str:"""列出指定目录下所有 Markdown 文件"""try:dir_path=Path(directory)ifnotdir_path.exists():returnf"❌ 目录不存在:{directory}"files=sorted(dir_path.glob("**/*.md"))ifnotfiles:returnf"📭 目录{directory}下没有找到 .md 文件"result=f"📂 共找到{len(files)}个文件:\n\n"forfinfiles:result+=f" -{f.relative_to(dir_path)}\n"returnresultexceptExceptionase:returnf"❌ 列表失败:{e}"# 启动服务器mcp.run()

代码解读：

FastMCP是官方提供的高层封装，比底层mcp.Server简洁很多
@mcp.tool()装饰器把一个普通 Python 函数注册为 AI 可调用的"工具"
工具参数用类型注解描述，LLM 会自动理解每个参数含义
返回值是字符串，会直接喂给 LLM 做后续分析

步骤 2：启动服务器

# 先激活虚拟环境source~/mcp-tutorial-venv/bin/activate# 启动 MCP 服务器（使用 stdio 传输模式）python ~/mcp-tutorial/file_read_server.py

stdio模式是最常见的方式，MCP Host 会像子进程一样启动它，通过标准输入输出通信。

步骤 3：在 Claude Desktop 中配置 MCP Server

打开 Claude Desktop 的配置文件（macOS 路径~/Library/Application Support/Claude/claude_desktop_config.json，Windows 路径%APPDATA%\Claude\claude_desktop_config.json），添加：

{"mcpServers":{"localFileReader":{"command":"python","args":["/home/ubuntu/mcp-tutorial/file_read_server.py"],"env":{"PATH":"/home/ubuntu/mcp-tutorial-venv/bin:$PATH"}}}}

保存后重启 Claude Desktop，你应该在聊天界面看到一个扳手图标 🔧，点击可以看到已连接的 MCP Server 工具列表。

步骤 4：在 Cursor 中配置（可选）

如果你用 Cursor，配置方式类似。打开cursor/settings.json：

{"cursor.mcpServers":{"localFileReader":{"command":"python","args":["/home/ubuntu/mcp-tutorial/file_read_server.py"]}}}

步骤 5：测试效果

重启 Host 后，直接问 AI：

帮我列出 /tmp 目录下所有的 .md 文件，然后读取其中一个看看内容。

AI 会自动调用你的 MCP 工具，流程完全自动化：

用户提问 ↓ Claude 识别需要"列文件"+"读文件" ↓ 自动调用 list_markdown_files("/tmp") ↓ 自动调用 read_markdown_file("/tmp/xxx.md") ↓ 整合结果，返回答案

四、进阶技巧：让 MCP 工具更强大

技巧 1：添加资源（Resources）

除了工具（Tool），MCP 还支持资源（Resource）。资源更像"文件接口"，适合直接暴露数据源：

@mcp.resource("docs://README")defget_readme():returnPath("/home/ubuntu/project/README.md").read_text()

这样 AI 可以直接引用docs://README这个 URI 获取内容，不需要调用函数。

技巧 2：给工具加详细描述

LLM 选择工具时依赖工具的 prompt 描述，写得越详细调用越准确：

@mcp.tool(description="当用户提到'日志'、'log'、'错误'时使用此工具，会搜索最近 24 小时的错误日志")defsearch_error_logs(days:int=1)->str:# ... 实现

技巧 3：安全沙箱

MCP 服务器本质是一个运行在你本机的程序，调用时务必注意：

风险点	建议
文件路径遍历	限制允许的目录白名单
敏感信息泄露	在返回值中脱敏
外部网络调用	添加请求频率限制

示例：限制读取路径

ALLOWED_DIRS=["/home/ubuntu/projects","/tmp"]defsafe_read(filepath:str):real_path=Path(filepath).resolve()ifnotany(str(d).startswith(str(allowed))forallowedinALLOWED_DIRS):returnf"❌ 不允许访问的路径:{filepath}"returnreal_path.read_text()