本地文件MCP服务器

Name: 本地文件MCP服务器
Author: Luxshan2000

作者：Luxshan20004 星标更新：2025-08-19

安装使用来源：spider==github.com

项目介绍

FastMCP 文件服务器

</div>

一款多功能、安全的文件服务器，实现了模型上下文协议（MCP），为AI助手提供安全的文件操作。支持多种连接模式、可配置访问级别以及全面的安全控制，适用于各种部署场景。

🚀 功能

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

📦 安装

从PyPI安装（推荐）

# 使用uv（推荐）
uv tool install fastmcp-file-server

# 使用pip
pip install fastmcp-file-server

从源代码安装

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

🔧 快速开始

基本用法

# 设置允许的目录
export MCP_ALLOWED_PATH="/path/to/your/files"

# 启动标准输入输出服务器（用于Claude桌面）
fastmcp-file-server

# 启动HTTP服务器
fastmcp-file-server-http

# 启动HTTP服务器，忽略安全警告（不推荐）
fastmcp-file-server-http --ignore-keys

带认证

# 设置HTTP模式下的管理员密钥
export MCP_ADMIN_KEY="your-secret-token"
export MCP_HTTP_PORT=8082
fastmcp-file-server-http

⚙️ 配置

环境变量

变量	默认值	描述
`MCP_ALLOWED_PATH`	`./allowed`	文件操作的目录路径
`MCP_HTTP_PORT`	`8082`	HTTP服务器端口
`MCP_READ_KEY`	`None`	只读访问令牌
`MCP_WRITE_KEY`	`None`	读写访问令牌
`MCP_ADMIN_KEY`	`None`	管理员访问令牌（包括删除）
`MCP_MAX_FILE_SIZE`	`10485760`	最大文件大小（字节，10MB）
`MCP_ALLOWED_EXTENSIONS`	`.txt,.json,.md,...`	允许的文件扩展名（逗号分隔）

配置文件

在项目根目录下创建一个.env文件：

# 必需：文件操作的安全目录
MCP_ALLOWED_PATH=/absolute/path/to/your/files

# 可选：HTTP服务器设置
MCP_HTTP_PORT=8082

# 可选：多级认证令牌
MCP_READ_KEY=readonly-token-here
MCP_WRITE_KEY=readwrite-token-here  
MCP_ADMIN_KEY=admin-token-here

# 可选：文件限制
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
Windows：%APPDATA%\Claude\config.json

标准输入输出模式（直接集成）

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

HTTP模式（本地服务器）

启动HTTP服务器：

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

配置Claude桌面：

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

HTTP模式带mcp-remote代理

对于需要代理的环境：

# 安装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

对于基于Web的AI系统（如ChatGPT等）：

# 终端1：启动认证HTTP服务器
export MCP_ADMIN_KEY="your-secret-token"
export MCP_HTTP_PORT=8082
fastmcp-file-server-http

# 终端2：通过ngrok公开访问
ngrok http 8082

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

URL：https://abc123.ngrok.io/mcp
Header：Authorization: Bearer your-secret-token

🔒 安全

安全特性

⚠️ HTTP模式安全警告：

当未配置任何认证令牌就启动HTTP服务器时，系统会显示安全警告并要求确认。这可以防止意外运行无保护的服务器。

# 这将触发安全警告：
fastmcp-file-server-http

# 跳过警告（不推荐）：
fastmcp-file-server-http --ignore-keys

令牌管理

⚠️ 重要安全提示：

有令牌：当设置了任何令牌（MCP_READ_KEY、MCP_WRITE_KEY或MCP_ADMIN_KEY）时，所有HTTP请求都需要Authorization: Bearer <token>头
无令牌：如果没有设置任何令牌，服务器将运行而无需认证（仅限于安全环境）
多级访问：不同的令牌提供不同的权限级别
临时暴露：对于ngrok或临时远程访问，始终使用强令牌并在完成后撤销访问
令牌轮换：定期轮换令牌，尤其是在临时暴露后

访问级别

未设置令牌：服务器运行而无需认证（标准输入输出模式安全，HTTP仅限本地）
读取令牌：MCP_READ_KEY - 文件列表、读取、搜索、比较操作
写入令牌：MCP_WRITE_KEY - 所有读取操作加上创建、修改、复制、移动、转换
管理员令牌：MCP_ADMIN_KEY - 所有操作包括文件和目录删除

最佳实践

永不提交秘密：使用.env文件（添加到.gitignore）
使用强令牌：生成加密安全随机令牌（openssl rand -hex 32）
限制访问范围：将MCP_ALLOWED_PATH设置为所需的最小目录
选择适当的令牌级别：使用只读令牌进行分析，仅在需要删除时使用管理员令牌
监控使用情况：检查日志以查找未经授权的访问尝试
临时访问：在临时暴露后取消所有令牌并重启

💡 使用示例

文件操作

# 基本操作
"创建名为notes.txt的文件，内容为我的会议记录"
"读取config.py的第10至20行"
"将config.json复制到backup/config_backup.json"

# 高级操作
"搜索所有Python文件中的'TODO'注释"
"将utils.py中的'old_function'替换为'new_function'"
"创建所有源文件的ZIP归档"
"将report.txt转换为PDF格式"
"计算important_file.pdf的SHA256哈希"

批量操作

"读取src/目录下的所有.py文件"
"创建这些5个配置文件及其内容"
"删除工作区中的所有.tmp文件"
"查找包含'console.log'的所有JavaScript文件"

🛠️ 开发

参见DEVELOPER.md了解详细的开发设置和贡献指南。

快速开发设置

# 克隆仓库
git clone https://github.com/Luxshan2000/Local-File-MCP-Server.git
cd Local-File-MCP-Server

# 安装依赖
uv sync

# 运行开发服务器
uv run server          # 标准输入输出模式
uv run server-http     # HTTP模式

# 运行测试和代码检查
uv run test
uv run lint
uv run format

📊 API参考

可用工具

工具	描述	访问级别
`read_file`	读取文件内容或特定行范围	只读
`write_file`	创建或覆盖文件	读写
`append_file`	追加内容到现有文件	读写
`delete_file`	删除文件和目录	管理员
`copy_file`	复制文件和目录	读写
`move_file`	移动/重命名文件和目录	读写
`list_directory`	列出目录内容并过滤	只读
`create_directory`	创建新目录	读写
`get_file_info`	获取文件元数据和权限	只读
`search_files`	按名称模式搜索文件	只读
`search_content`	使用正则表达式搜索文件内容	只读
`replace_content`	在文件中查找和替换文本	读写
`insert_lines`	在特定行号插入文本	读写
`delete_lines`	删除特定行范围	读写
`compare_files`	生成文件之间的差异	只读
`create_archive`	创建ZIP归档	读写
`extract_archive`	提取ZIP归档	读写
`calculate_hash`	生成文件哈希（MD5、SHA1、SHA256）	只读
`convert_document`	将文本转换为PDF	读写
`convert_image`	在图像格式之间转换	读写
`convert_data`	在CSV和JSON之间转换	读写

🐛 故障排除

常见问题

服务器无法启动：

# 重新安装依赖
uv sync

# 检查Python版本
python --version  # 需要Python 3.10+

Claude桌面无法连接：

验证配置中的所有路径都是绝对路径（完整路径）
更改配置后重启Claude桌面
检查服务器是否无错误启动：uv run server
确保MCP_ALLOWED_PATH目录存在且可访问

HTTP认证失败：

验证在启动服务器前已设置MCP_ADMIN_KEY
检查授权头格式：Bearer your-secret-token
确保令牌完全匹配（无额外空格）

权限被拒绝错误：

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

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

🤝 贡献

我们欢迎贡献！请参阅DEVELOPER.md了解开发设置和CODE_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上给它一个星！