Skip to main content
Glama
filesystem

filesystem

by Ruadgedy

MCP 入门案例:文件操作 Server

一个最小可运行的 MCP(Model Context Protocol)Server,用 Python 官方 v2 SDK 写成, 暴露三个文件操作工具,供 MCP Inspector 调试验证。

MCP 三层架构速记

┌──────────────┐   stdio/HTTP   ┌──────────┐   子进程   ┌──────────────────┐
│   Host       │◀─────────────▶│  Client  │◀──────────▶│  Server (本项目)  │
│ Claude Desktop│               │(Host 内部)│  stdin/stdout│  filesystem.py   │
│  Inspector   │               │          │            │  暴露 Tools/...   │
└──────────────┘               └──────────┘            └──────────────────┘
  • Host:跑大模型的应用(Claude Desktop、Inspector 等),内部管理 Client。

  • Client:与某个 Server 建立 1:1 连接,按 MCP 协议收发消息。

  • Server:你写的程序,向模型暴露三类能力。本例只用了最常用的 Tool:

    • read_file / write_file / list_directory

Related MCP server: files-mcp-ts

环境与安装

需要 Python ≥ 3.10(本机用 3.13)和 uv。依赖已写在 pyproject.toml:

uv sync          # 安装依赖、创建虚拟环境

核心依赖是 mcp[cli]>=2.0.0(v2 用 MCPServer 取代了旧版 FastMCP)。

用 MCP Inspector 调试

Inspector 是官方图形化工具,能直接看到模型/客户端如何调用你的工具,无需配置 Claude Desktop。

uv run mcp dev servers/filesystem.py

启动后会打印一个本地网址(默认 http://127.0.0.1:6274 ),浏览器打开即可。在左侧 “Tools” 里能看到三个工具,点开 -> 填参数 -> 点 “Run Tool” 看返回。

建议按这个顺序试一遍,体会完整流程:

  1. list_directory(path 留空走默认 .)-> 应看到 hello.txt

  2. read_file,path 填 hello.txt -> 读到示例内容

  3. write_file,path 填 test.txt、content 随便写 -> 提示写入成功

  4. 再 list_directory -> 应看到新增的 test.txt

  5. 安全测试:read_file path 填 ../secret -> 应被拒绝(沙箱拦截路径穿越)

程序化验证(不走 Inspector)

不启动 Inspector,用 v2 内存 Client 直接连 server 对象跑一遍工具,适合快速回归:

uv run python tests/test_filesystem.py
# 或:uv run python -m tests.test_filesystem

目录结构

mcp-test/
├── pyproject.toml          # uv 项目 + 依赖声明
├── uv.lock                 # 依赖锁文件(提交进 git 保证可复现)
├── servers/
│   └── filesystem.py       # MCP Server:三个文件操作 Tool
├── tests/
│   └── test_filesystem.py  # 冒烟测试(内存 Client 直连)
├── workspace/              # 沙箱目录,所有文件操作只能在此内进行
│   └── hello.txt           # 示例文件(运行时产生的文件被 .gitignore 忽略)
└── README.md

所有工具的路径都解析到 workspace/ 之内,并用 resolve() + 父目录校验拦截 ../ 之类的路径穿越。这是 MCP Server 编写的安全要点:永远校验模型传进来的路径。

关键代码点

  • from mcp.server import MCPServer - v2 的入口(不是旧版 mcp.server.fastmcp.FastMCP)

  • @mcp.tool() 装饰一个普通函数 - 函数名、docstring、类型注解就是工具的全部元数据

  • if __name__ == "__main__": mcp.run() - 无参数即 stdio 传输;守卫不可省, 因为 mcp dev 会先 import 本文件

  • 调试走 logging(输出到 stderr)- stdio 模式下 stdout 是协议链路,不能用 print

下一步

把 Server 接入 Claude Desktop,在真实对话里用上它:

uv run mcp install servers/filesystem.py --name "filesystem"

这会自动写入 Claude Desktop 的 claude_desktop_config.json,重启 Desktop 后即可在对话中 让模型读写 workspace/ 里的文件。

参考文档

Available Tools

3 tools
list_directoryA

列出 workspace 内某个目录下的条目,每行标注 FILE 或 DIR。

Args: path: 相对于 workspace 的目录路径,默认为 workspace 根目录。

Inputs: path. Returns: result

read_fileA

读取 workspace 内某个文本文件的内容并返回。

Args: path: 相对于 workspace 的文件路径,例如 "hello.txt" 或 "notes/a.txt"。

Inputs: path (required). Returns: result

write_fileA

把文本内容写入 workspace 内的文件;文件或上级目录不存在则自动创建。

Args: path: 相对于 workspace 的文件路径。 content: 要写入的文本,会整体覆盖已有内容。

Inputs: path (required), content (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a single, clear purpose: reading, writing, or listing. There is no overlap between these operations, so an agent can easily select the correct tool.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: read_file, write_file, list_directory. This makes the API predictable and easy to remember.

    Tool Count3/5

    Three tools is a minimal set. While it covers basic file operations, a typical filesystem server would also include delete, rename, or move operations, making the count feel thin for the advertised scope.

    Completeness2/5

    The server lacks common filesystem operations such as delete, rename, move, and directory creation. This is a significant gap; for example, an agent cannot clean up or reorganize files after creating them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools for secure file management within a dedicated workspace directory. It enables users to create, list, and delete files through natural language while preventing path traversal attacks.
      ISC
    • F
      license
      B
      quality
      D
      maintenance
      A lightweight MCP server for basic file operations, enabling reading, writing, and listing files securely via the Model Context Protocol.
      3
      1
      -