本地文件MCP服务器
A. 模型上下文协议（MCP） 启用的服务器 Claude Desktop（可译为“克劳德桌面版”或保持原名“Claude Desktop”，具体取决于语境和品牌偏好） 为了安全地与您的本地文件系统进行交互，该服务器采用C# .NET 8.0构建，提供在您主目录内的安全文件操作，使Claude能够直接在您的计算机上读取、写入、列出和管理文件。
🤖 这是什么？
这个MCP服务器填补了（或连接了）……之间的鸿沟 Claude Desktop（克劳德桌面版） （Anthropic的桌面应用程序）以及您的本地文件系统。配置完成后，您可以要求Claude：
- “列出我文档文件夹中的所有文件”
- “阅读我项目中的README文件内容”
- “创建一个名为 hello.py 的新 Python 脚本”
- “删除我下载文件夹中的临时文件”
服务器使用 模型上下文协议这是一种标准化的方式，让AI助手能够安全地访问外部资源。它通过stdin/stdout使用JSON-RPC 2.0与Claude Desktop进行通信，提供了一个安全的沙盒环境，将所有操作限制在您的主目录内。
🌟 特点
- 🔒 安全所有操作均限于您的主目录内进行
- 📁 文件浏览列出文件和目录及其详细元数据
- 📖 文件读取读取文本文件，具备编码检测和大小限制功能
- ✏️ 文件写入以原子写入操作创建和编辑文件
- 🗑️ 文件删除在安全检查后删除文件和目录
- 🛡️ 安全第一二进制文件检测、大小限制、路径验证
🚀 快速入门
先决条件
- .NET 8.0 SDK（软件开发工具包） 或之后
- Windows、macOS 或 Linux
安装
选项1：自动设置（推荐）
- 克隆仓库：
git clone https://github.com/your-username/local-files-mcp-server.git
cd local-files-mcp-server- 运行安装脚本：
.\setup.ps1这将会：
- 构建并发布MCP服务器 - 自动配置Claude桌面版 - 创建必要的配置文件
- 重启Claude桌面版 并查找“✅ 本地文件：已连接”
💡（这个符号本身没有直接的中文翻译，但它通常代表“灯泡”或“灵感”的意思，在中文网络用语中可以表示“想法”或“创意”。） 小贴士您可以在Claude Desktop中通过以下路径验证MCP服务器的连接状态： 设置 → 开发者 在那里，您将看到所有已配置的MCP服务器及其连接状态。
选项2：手动设置
- 克隆并构建：
git clone https://github.com/your-username/local-files-mcp-server.git
cd local-files-mcp-server
dotnet build- 对于Claude Desktop的集成：
- 发布可执行文件： dotnet publish -c Release -o publish --self-contained true -r win-x64 /p:PublishSingleFile=true - 复制 claude_desktop_config.json to %APPDATA%\Claude\claude_desktop_config.json - 编辑配置文件以替换 PATH_TO_REPO 使用您实际的仓库路径 - 重启Claude桌面版
- 直接使用方法：
dotnet run --project LocalFilesMcpServer服务器通过（某种方式）进行通信 标准输入/标准输出 使用JSON-RPC 2.0协议。
截图
在Claude Desktop中查看MCP服务器的运行情况：
这些截图展示了通过Claude Desktop集成所实现的完整文件管理流程。
📋 可用工具
1. list_files - 浏览目录内容
列出带有元数据的文件和目录
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_files",
"arguments": {
"path": "Documents"
}
}
}2. read_file - 读取文件内容
读取最大50MB的文本文件
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {
"path": "Documents/example.txt"
}
}
}3. write_file - 创建/编辑文件
以原子操作将内容写入文件
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "write_file",
"arguments": {
"path": "Documents/new_file.txt",
"content": "Hello, World!\nThis is a new file."
}
}
}4. delete_file - 删除文件/目录
删除文件或目录（对于目录递归删除）
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "delete_file",
"arguments": {
"path": "Documents/old_file.txt"
}
}
}🔧 使用示例
完整工作流示例
# Initialize MCP session
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}' | dotnet run --project LocalFilesMcpServer
# List available tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | dotnet run --project LocalFilesMcpServer
# Browse files in Documents folder
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_files","arguments":{"path":"Documents"}}}' | dotnet run --project LocalFilesMcpServer交互式测试
创建一个测试脚本（test_session.txt):
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_files","arguments":{"path":"."}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"test.txt","content":"Hello MCP!"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"test.txt"}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"delete_file","arguments":{"path":"test.txt"}}}运行它：
type test_session.txt | dotnet run --project LocalFilesMcpServer🛡️ 安全特性
- 主目录限制所有路径均相对于您的主目录解析
- 路径验证防止目录遍历攻击（例如。，
../../../etc/passwd) - 文件大小限制读取限制为50MB，写入限制为50MB
- 二进制文件检测自动检测并拒绝读取二进制文件
- 权限检查在操作前验证读/写权限
- 原子写入文件以原子方式写入（临时文件 + 移动）以防止损坏
📁 项目结构
LocalFilesMcpServer/
├── Models/ # MCP protocol message models
│ ├── McpMessage.cs # Base JSON-RPC 2.0 classes
│ ├── InitializeMessage.cs
│ ├── ToolMessage.cs
│ ├── CallToolMessage.cs
│ ├── Tool.cs
│ └── FileItem.cs
├── Services/ # Core business logic
│ ├── McpProtocolHandler.cs # MCP protocol routing
│ ├── FileOperationService.cs # File system operations
│ └── PathValidationService.cs # Security validation
├── Tools/ # Individual tool implementations
│ ├── ListFilesTool.cs
│ ├── ReadFileTool.cs
│ ├── WriteFileTool.cs
│ └── DeleteFileTool.cs
└── Program.cs # Application entry point🔍 错误处理
服务器提供详细的错误信息，这些信息紧跟在MCP错误代码之后：
- -32700解析错误（JSON格式错误）
- -32600无效请求
- -32601未找到方法
- -32602无效参数
- -32603内部错误
- -32002服务器未初始化
示例错误响应：
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Error: File not found. Action: Provide a valid file path for file access"
}
}🧪 开发
构建与测试
# Build the project
dotnet build
# Run all tests (when implemented)
dotnet test
# Check code formatting
dotnet format --verify-no-changes📖 MCP 协议
这个服务器实现了 模型上下文协议 规格：
- 协议版本:
2024-11-05并且2025-06-18（多版本支持以确保兼容性） - 交通stdio（stdin/stdout）
- 消息格式JSON-RPC 2.0
- 能力工具（文件操作）
📝 许可证
这个项目采用MIT许可证授权——详见 许可证 文件中详述。
______________________________________________________________________
用Claude快乐地管理文件！ 🚀