前言你有没有遇到过这种场景你让 Claude 帮你分析一份本地的 CSV 销售数据或者读取某个目录下的日志文件结果它一脸无辜地说我无法访问你的文件问题不在于 Claude 不够聪明而在于它缺少手。大型语言模型默认是纯文本接口看不到你本地的文件、数据库、API。而MCPModel Context Protocol模型上下文协议正是为了解决这个问题而生的标准协议——它让 AI 客户端如 Claude Desktop、Cursor、VS Code通过统一的协议调用你本地的工具和服务。今天这篇博客我带你从零搭建一个 MCP 服务器把你的本地文件系统变成一个 AI 可以直接摸到的数据源。一、MCP 到底是什么大白话解释你可以把 MCP 理解成AI 和外部世界之间的翻译官。传统模式下AI 只有一个聊天窗口你能发的只有文字。有了 MCP 之后AI 可以读取你的本地文件日志、配置、数据库调用你写的 Python 脚本连接外部 API天气、股票、Jira 等MCP 的核心架构只有三个角色角色职责举例Host客户端发起请求转发给 LLMClaude Desktop、Cursor、VS CodeMCP 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 SDKpipinstallmcp[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.pyfrommcp.server.fastmcpimportFastMCPfrompathlibimportPath# 初始化 MCP 服务器mcpFastMCP(LocalFileReader,description读取本地目录下的 Markdown 文件)# 定义第一个工具读取单个文件mcp.tool()defread_markdown_file(filepath:str)-str:读取指定的 Markdown 文件内容try:pathPath(filepath)ifnotpath.exists():returnf❌ 文件不存在:{filepath}ifnotpath.suffix.md:returnf❌ 只支持 .md 文件当前后缀:{path.suffix}returnpath.read_text(encodingutf-8)exceptExceptionase:returnf❌ 读取失败:{e}# 定义第二个工具列出目录下所有 md 文件mcp.tool()deflist_markdown_files(directory:str)-str:列出指定目录下所有 Markdown 文件try:dir_pathPath(directory)ifnotdir_path.exists():returnf❌ 目录不存在:{directory}filessorted(dir_path.glob(**/*.md))ifnotfiles:returnf 目录{directory}下没有找到 .md 文件resultf 共找到{len(files)}个文件:\n\nforfinfiles:resultf -{f.relative_to(dir_path)}\nreturnresultexceptExceptionase: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.pystdio模式是最常见的方式MCP Host 会像子进程一样启动它通过标准输入输出通信。步骤 3在 Claude Desktop 中配置 MCP Server打开 Claude Desktop 的配置文件macOS 路径~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 路径%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除了工具ToolMCP 还支持资源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:int1)-str:# ... 实现技巧 3安全沙箱MCP 服务器本质是一个运行在你本机的程序调用时务必注意风险点建议文件路径遍历限制允许的目录白名单敏感信息泄露在返回值中脱敏外部网络调用添加请求频率限制示例限制读取路径ALLOWED_DIRS[/home/ubuntu/projects,/tmp]defsafe_read(filepath:str):real_pathPath(filepath).resolve()ifnotany(str(d).startswith(str(allowed))forallowedinALLOWED_DIRS):returnf❌ 不允许访问的路径:{filepath}returnreal_path.read_text()五、总结今天我们从零搭建了一个 MCP 文件读取服务器核心要点回顾MCP 是 AI 与外部工具的标准化桥梁让 LLM 能读写文件、调用脚本、连接 API使用mcp[cli]和FastMCP可以在 30 行代码内创建一个 MCP Server配置 Claude Desktop / Cursor 即可将工具接入日常使用进阶玩法包括资源暴露、工具描述优化、安全沙箱下一步建议试试把你的 Jira、GitHub Issues、或公司内网 API 通过 MCP 接进来。一旦工具链搭好你会发现 AI 从聊天机器人进化成了真正的工作助手。动手试试有问题在评论区见