filesystem
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@filesystem list files in the workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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” 看返回。
建议按这个顺序试一遍,体会完整流程:
list_directory(path 留空走默认.)-> 应看到hello.txtread_file,path 填hello.txt-> 读到示例内容write_file,path 填test.txt、content 随便写 -> 提示写入成功再
list_directory-> 应看到新增的test.txt安全测试:
read_filepath 填../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/ 里的文件。
参考文档
MCP 协议官网:https://modelcontextprotocol.io
Python SDK 文档:https://py.sdk.modelcontextprotocol.io
Available Tools
3 toolslist_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
Scored across 3 tools
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.
All tool names follow a consistent verb_noun pattern: read_file, write_file, list_directory. This makes the API predictable and easy to remember.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Browse and manage files in your Moxt AI workspace from any MCP client.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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
- FlicenseBqualityDmaintenanceA lightweight MCP server for basic file operations, enabling reading, writing, and listing files securely via the Model Context Protocol.31-
- FlicenseAqualityDmaintenanceA safe MCP server for sandboxed filesystem operations (list, move, create directories, delete files) via pure Python, designed for Claude Desktop.5-
- FlicenseAqualityDmaintenanceAn MCP server that exposes filesystem operations — listing directories, reading, writing, and searching files — as tools an LLM can discover and invoke at runtime.4-