Fastmcp File Server

FastMCP文件服务器

一个多功能、安全的文件服务器，实现了模型上下文协议（MCP），为AI助手提供安全的文件操作。具有多种连接模式、可配置的访问级别和针对各种部署场景的全面安全控制。

🚀 特性

• 全面的文件操作：创建、读取、写入、删除、复制、移动、重命名文件和目录
• 高级文本操作：特定行操作、搜索和替换、模式匹配
• 文件分析：大小、权限、时间戳、哈希验证、差异生成
• 批量操作：在单个操作中高效处理多个文件
• 存档支持：创建和提取ZIP文件
• 格式转换：文本到PDF、图像格式转换、CSV↔ 对象符号
• 多种连接模式：stdio、HTTP和通过ngrok的公共访问
• 分层访问控制：只读、读/写和管理员权限级别
• 安全第一：所有操作仅限于配置的安全目录

📦 安装

来自PyPI（推荐）

# Using uv (recommended)
uv tool install fastmcp-file-server

# Using pip
pip install fastmcp-file-server

来源

git clone https://github.com/Luxshan2000/Local-File-MCP-Server.git
cd Local-File-MCP-Server
uv sync

🔧 快速开始

基本用法

# Set allowed directory
export MCP_ALLOWED_PATH="/path/to/your/files"

# Start stdio server (for Claude Desktop)
fastmcp-file-server

# Start HTTP server
fastmcp-file-server-http

# Start HTTP server bypassing security warning (not recommended)
fastmcp-file-server-http --ignore-keys

通过身份验证

# Set admin key for HTTP mode
export MCP_ADMIN_KEY="your-secret-token"
export MCP_HTTP_PORT=8082
fastmcp-file-server-http

⚙️ 配置

环境变量

配置文件

创建一个 .env 项目根目录中的文件：

# Required: Safe directory for file operations
MCP_ALLOWED_PATH=/absolute/path/to/your/files

# Optional: HTTP server settings
MCP_HTTP_PORT=8082

# Optional: Multi-tier authentication tokens
MCP_READ_KEY=readonly-token-here
MCP_WRITE_KEY=readwrite-token-here  
MCP_ADMIN_KEY=admin-token-here

# Optional: File restrictions
MCP_MAX_FILE_SIZE=10485760
MCP_ALLOWED_EXTENSIONS=.txt,.json,.md,.csv,.log,.xml,.yaml,.yml,.conf,.cfg,.zip,.pdf,.jpg,.png

🔗 整合

Claude桌面集成

配置文件位置：

• macOS: ~/Library/Application Support/Claude/config.json
• 视窗: %APPDATA%\Claude\config.json

标准模式（直接集成）

{
  "mcpServers": {
    "local-file-server": {
      "command": "fastmcp-file-server",
      "env": {
        "MCP_ALLOWED_PATH": "/absolute/path/to/your/allowed/directory"
      }
    }
  }
}

HTTP模式（本地服务器）

1. 启动HTTP服务器：

export MCP_ADMIN_KEY="your-secret-token"
fastmcp-file-server-http

1. 配置Claude桌面：

{
  "mcpServers": {
    "local-file-server-http": {
      "transport": "http",
      "url": "http://127.0.0.1:8082/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

带有mcp远程代理的HTTP模式

对于需要代理的环境：

# Install mcp-remote
npm install -g mcp-remote

{
  "mcpServers": {
    "local-file-server-proxy": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8082/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer your-secret-token"
      }
    }
  }
}

公众访问与ngrok

对于基于网络的人工智能系统（ChatGPT等）：

# Terminal 1: Start authenticated HTTP server
export MCP_ADMIN_KEY="your-secret-token"
export MCP_HTTP_PORT=8082
fastmcp-file-server-http

# Terminal 2: Expose publicly via ngrok
ngrok http 8082

在基于web的AI系统中使用ngrok URL：

• 统一资源定位符: https://abc123.ngrok.io/mcp
• 头球: Authorization: Bearer your-secret-token

🔒 安全

安全功能

⚠️ HTTP模式安全警告：

在未配置任何身份验证令牌的情况下启动HTTP服务器时，系统将显示安全警告并提示确认。这可以防止意外运行未受保护的服务器。

# This will trigger a security warning:
fastmcp-file-server-http

# To bypass the warning (not recommended):
fastmcp-file-server-http --ignore-keys

许可证管理

⚠️ 重要安全注意事项：

• 带钥匙：设置任何令牌时(MCP_READ_KEY, MCP_WRITE_KEY，或 MCP_ADMIN_KEY)，所有HTTP请求都需要 Authorization: Bearer 头球
• 没有钥匙：如果没有设置令牌，服务器将在没有身份验证的情况下运行（仅在安全环境中使用）
• 多层访问：不同的令牌提供不同的权限级别
• 临时暴露：对于ngrok或临时远程访问，始终使用强令牌，并在完成后撤销访问
• 关键点旋转：定期轮换代币，尤其是在临时曝光之后

访问级别

• 未设置令牌：服务器在没有身份验证的情况下运行（stdio模式安全，仅HTTP本地）
• 读取令牌: MCP_READ_KEY -文件列表、读取、搜索、比较操作
• 写入令牌: MCP_WRITE_KEY -所有读取操作以及创建、修改、复制、移动、转换
• 管理员令牌: MCP_ADMIN_KEY -所有操作，包括文件和目录删除

最佳实践

1. 永远不要泄露秘密：使用 .env 文件（添加到 .gitignore)
2. 使用强令牌：生成加密安全的随机令牌(openssl rand -hex 32)
3. 限制访问范围：设置 MCP_ALLOWED_PATH 到所需的最小目录
4. 选择适当的令牌级别：使用只读令牌进行分析，仅在需要删除时使用管理员
5. 监控使用情况：检查日志中是否有未经授权的访问尝试
6. 临时通道：取消设置所有令牌，并在临时暴露后重新启动

💡 使用示例

文件操作

# Basic operations
"Create a file called notes.txt with my meeting notes"
"Read lines 10-20 from config.py"
"Copy config.json to backup/config_backup.json"

# Advanced operations
"Search for 'TODO' comments in all Python files"
"Replace 'old_function' with 'new_function' in utils.py"
"Create a ZIP archive of all source files"
"Convert report.txt to PDF format"
"Calculate SHA256 hash of important_file.pdf"

批量操作

"Read all .py files in the src/ directory"
"Create these 5 configuration files with their content"
"Delete all .tmp files in the workspace"
"Find all JavaScript files containing 'console.log'"

🛠️ 发展

看 开发商.md 详细的开发设置和贡献指南。

快速开发设置

# Clone repository
git clone https://github.com/Luxshan2000/Local-File-MCP-Server.git
cd Local-File-MCP-Server

# Install dependencies
uv sync

# Run development server
uv run server          # stdio mode
uv run server-http     # HTTP mode

# Run tests and linting
uv run test
uv run lint
uv run format

📊 api参考

可用工具

🐛 故障排除

常见问题

服务器无法启动：

# Reinstall dependencies
uv sync

# Check Python version
python --version  # Requires Python 3.10+

Claude Desktop未连接：

1. 验证配置中的所有路径都是绝对路径（完整路径）
2. 更改配置后重新启动Claude Desktop
3. 检查服务器是否正常启动： uv run server
4. 确保 MCP_ALLOWED_PATH 目录存在并且可以访问

HTTP身份验证失败：

1. 验证 MCP_ADMIN_KEY 在启动服务器之前设置
2. 检查授权标头格式： Bearer your-secret-token
3. 确保令牌完全匹配（没有额外空格）

权限被拒绝错误：

1. 检查文件/目录权限
2. 验证 MCP_ALLOWED_PATH 可访问
3. 确保用户在允许的目录中具有读/写权限

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🤝 贡献

我们欢迎捐款！请看 开发商.md 用于开发设置和 代码_OF_CONDUCT.md 社区指南。

🔗 链接

• 仓库: https://github.com/Luxshan2000/Local-File-MCP-Server
• PyPI包: https://pypi.org/project/fastmcp-file-server/
• 问题: https://github.com/Luxshan2000/Local-File-MCP-Server/issues
• 模型上下文协议: https://modelcontextprotocol.io/

⭐ 支持

如果你觉得这个项目有用，请考虑在GitHub上给它一颗星！