前言

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

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

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

---

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

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

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

1. 读取你的本地文件（日志、配置、数据库）

2. 调用你写的 Python 脚本

3. 连接外部 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 -m venv ~/mcp-tutorial-venv
source ~/mcp-tutorial-venv/bin/activate

# 安装 MCP SDK
pip install "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：

from mcp.server.fastmcp import FastMCP
from pathlib import Path

# 初始化 MCP 服务器
mcp = FastMCP(
    "LocalFileReader",
    description="读取本地目录下的 Markdown 文件"
)

# 定义第一个工具：读取单个文件
@mcp.tool()
def read_markdown_file(filepath: str) -> str:
    """读取指定的 Markdown 文件内容"""
    try:
        path = Path(filepath)
        if not path.exists():
            return f"❌ 文件不存在: {filepath}"
        if not path.suffix == ".md":
            return f"❌ 只支持 .md 文件，当前后缀: {path.suffix}"
        return path.read_text(encoding="utf-8")
    except Exception as e:
        return f"❌ 读取失败: {e}"

# 定义第二个工具：列出目录下所有 md 文件
@mcp.tool()
def list_markdown_files(directory: str) -> str:
    """列出指定目录下所有 Markdown 文件"""
    try:
        dir_path = Path(directory)
        if not dir_path.exists():
            return f"❌ 目录不存在: {directory}"
        files = sorted(dir_path.glob("**/*.md"))
        if not files:
            return f"📭 目录 {directory} 下没有找到 .md 文件"
        result = f"📂 共找到 {len(files)} 个文件:\n\n"
        for f in files:
            result += f"  - {f.relative_to(dir_path)}\n"
        return result
    except Exception as e:
        return f"❌ 列表失败: {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")
def get_readme():
    return Path("/home/ubuntu/project/README.md").read_text()

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

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

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

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

技巧 3：安全沙箱

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

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

示例：限制读取路径

ALLOWED_DIRS = ["/home/ubuntu/projects", "/tmp"]

def safe_read(filepath: str):
    real_path = Path(filepath).resolve()
    if not any(str(d).startswith(str(allowed)) for allowed in ALLOWED_DIRS):
        return f"❌ 不允许访问的路径: {filepath}"
    return real_path.read_text()

---

五、总结

今天我们从零搭建了一个 MCP 文件读取服务器，核心要点回顾：

1. MCP 是 AI 与外部工具的标准化桥梁，让 LLM 能读写文件、调用脚本、连接 API

2. 使用 mcp[cli] 和 FastMCP 可以在 30 行代码内创建一个 MCP Server

3. 配置 Claude Desktop / Cursor 即可将工具接入日常使用

4. 进阶玩法包括资源暴露、工具描述优化、安全沙箱

下一步建议： 试试把你的 Jira、GitHub Issues、或公司内网 API 通过 MCP 接进来。一旦工具链搭好，你会发现 AI 从"聊天机器人"进化成了真正的"工作助手"。

动手试试，有问题在评论区见 👇