FileOps MCP服务器
一个全面的MCP服务器，通过Claude和其他LLM客户端使用Git版本控制实现安全的文件系统操作。
概述
FileOps允许LLM：
- 创建、读取、更新和删除文本文件
- 创建和删除目录
- 生成针对LLM优化的可视化文件树
- 搜索与模式匹配的文件
- 与Git集成的版本文件（新）
- 所有这些都具有可配置的安全限制
特性
资源
| URI模式 | 描述 |
|---|---|
file://{path} | 访问文件内容 |
dir://{path} | 查看目录内容 |
filetree://{path} | 获取格式化的目录树 |
stats://{path} | 获取详细的文件/目录统计信息 |
gitlog://{path} | 查看Git提交历史记录（新） |
gitversion://{path} | 查看当前版本的文件（新） |
gitversion://{path}?version={commit_id} | 在特定提交时查看文件（新） |
gitstatus://{path} | 查看Git存储库状态（新） |
工具
| 工具 | 用途 | 参数 |
|---|---|---|
read_file | 读取文件内容 | path：要读取的文件 |
start_line：可选起始行号（1-索引） end_line：可选结束行号（1-索引）| | read_multiple_files |一次读取多个文件| paths：要读取的文件路径列表| | create_file |创建新的文本文件| path：位置 content：文件内容 commit_message：自定义Git提交消息（可选）| | update_file |更改文件中的文本| path：目标文件 old_string：要替换的文本 new_string：替换文本 old_str：old_string的替代参数名称（LLM兼容性备份） new_str：new_string的替代参数名称（LLM兼容性备份） commit_message：自定义Git提交消息（可选）| | rewrite_file |替换整个文件| path：目标文件 content：新内容 commit_message：自定义Git提交消息（可选）| | delete_file |删除文件| path：要删除的文件 commit_message：自定义Git提交消息（可选）| | remove_from_file |删除特定文本| path：目标文件 old_string：要删除的文本 commit_message：自定义Git提交消息（可选）| | append_to_file |在文件末尾添加文本| path：目标文件 content：要附加的文本 commit_message：自定义Git提交消息（可选）| | insert_in_file |在特定位置插入文本| path：目标文件 content：要插入的文本 after_line：要插入的行号（0索引）或 before_line：要插入的行号（0索引）或 after_pattern：要插入的文本模式 commit_message：自定义Git提交消息（可选）| | copy_file |复制文件| path：源文件 dest_path：目标文件 commit_message：自定义Git提交消息（可选）| | move_file |移动/重命名文件| path：源文件 dest_path：目标文件 commit_message：自定义Git提交消息（可选）| | move_multiple_files |移动多个文件| source_paths：源文件路径列表 dest_paths：目标文件路径列表（如果提供，则必须与源路径长度匹配） dest_dir：目标目录（dest_paths的替代品） commit_message：自定义Git提交消息（可选）| | create_dir |创建新文件夹| path：要创建的目录 commit_message：自定义Git提交消息（可选）| | delete_dir |删除目录| path：要删除的目录 recursive：删除内容（可选） commit_message：自定义Git提交消息（可选）| | get_tree |显示文件夹结构| path：起始目录 max_depth：树深度（可选）| | search_files |按模式查找文件| directory：在哪里搜索 pattern：找什么 max_results：限制结果（可选）| | find_in_files |在文件中搜索文本| directory：在哪里搜索 text：要查找的文本 file_pattern：文件过滤器（可选） max_results：限制结果（可选）| | git_init |初始化存储库| path：在哪里创建存储库（新）| | git_commit |提交更改| path：文件或目录 message：描述性提交消息（推荐）| | git_log |查看提交历史记录| path：文件路径 max_count：提交次数（新）| | git_show |提交时查看文件| path：文件路径 commit_id：提交引用（新）| | git_diff |比较版本| path：文件路径 commit1：基础承诺 commit2：比较提交（新）| | git_revert |还原以前的版本| path：文件路径 commit_id：目标承诺（新）| | git_status |显示存储库状态| path：存储库路径（新）| | git_branch_list |列出所有分支| path：存储库路径（新）| | git_branch_create |创建新分支| path：存储库路径 branch_name：新分支机构的名称（new）| | git_branch_switch |切换到分支| path：存储库路径 branch_name：目标分支（新）|
安装和设置
UV快速入门
# Install UV (if needed)
# For macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# For Windows PowerShell
powershell -ExecutionPolicy Bypass -Command "irm https://astral.sh/uv/install.ps1 | iex"
# Clone the repository
git clone https://github.com/yourusername/fileops-mcp.git
cd fileops-mcp
# Set up environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
uv pip install -e .
# Test in development mode
uv run src/main.py
# Or run with specific options
uv run src/main.py --working-dir /path/to/dir --read-onlypip替代品
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install from PyPI
pip install fileops-mcp
# Or install locally
pip install -e .
# Test the server
python -m src.mainClaude桌面配置
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Roaming\Claude\claude_desktop_config.json （Windows）：
{
"mcpServers": {
"fileops": {
"command": "uv",
"args": [
"--directory",
"Z:/Claude/mcp-server/fileops-mcp",
"run",
"src/main.py"
],
"env": {
"WORKING_DIR": "Z:/Claude/mcp-server/fileops-mcp/working-dir",
"READ_ONLY": "false",
"GIT_ENABLED": "true",
"GIT_AUTO_COMMIT": "true"
}
}
}
}使用MCP CLI进行安装
如果安装了MCP CLI，则可以使用它直接安装服务器：
# Install in Claude Desktop
uv run mcp install src/main.py --name "FileOps" --env WORKING_DIR="/path/to/dir" --env GIT_ENABLED="true"使用示例
在克劳德桌面
- “请在~/Documents/notes.txt中创建一个包含今天笔记的新文件”
- “显示下载文件夹中有哪些文件”
- “阅读我的README.md文件的内容并提出改进建议”
- “从log.txt文件中读取第10-50行以查看最近的条目”
- “阅读package.json和tsconfig.json文件以了解项目设置”
- 通过将“正在进行”替换为“已完成”来更新我的TODO.txt文件
- “在Python类的构造函数后插入一个新方法”
- “生成项目目录的文件树视图”
- “搜索我项目中的所有Python文件”
- “在我的项目文件中查找所有出现的'TODO'”
- “将我的config.json文件复制到config.backup.json”
- “将draft.txt文件移动到final/published.txt”
- “将我的所有.log文件从temp/移动到archive/目录”
- “在我的项目文件夹中初始化Git存储库”（新建）
- “显示main.py的提交历史记录”（新）
- “将当前版本的config.json与以前的版本进行比较”（新）
- “将README.md还原为2次提交前的版本”（新）
- “列出我的存储库中的所有分支”（新）
- “创建一个名为“功能登录”的新分支”（新建）
- “切换到‘开发’分支”（新）
Git集成功能
新的Git集成允许您：
- 跟踪更改：每次文件修改都会自动提交（可选）
- 历史记录：查看谁更改了什么以及何时更改
- 比较版本：查看文件版本之间的差异
- 还原以前的版本：将文件还原为早期状态
- 管理存储库：初始化、提交和检查状态
- 与分支机构合作：为不同的功能或版本创建分支
- 在分支之间切换：更改工作分支以隔离更改
- 使用自定义提交消息：添加使用标准前缀自动格式化的描述性提交消息：
[operation] path: your_message
Git分支使您能够：
- 同时处理多个功能，不受干扰
- 创建隔离的测试环境
- 维护文件的不同版本
- 在发展特色分支的同时，保持主分支的稳定
默认情况下，Git操作会自动提交更改，但可以使用禁用 --disable-auto-commit.
配置选项
您可以使用以下方式配置服务器：
环境变量
WORKING_DIR：允许访问的目录（默认：当前目录）READ_ONLY：设置为“true”以禁用所有写入操作（默认值：“false”）HIDE_DOT_FILES：设置为“false”以显示隐藏文件（默认值：“true”）MAX_DEPTH：目录遍历的最大深度（默认值：5，最大值：10）MAX_RESULTS：搜索操作的最大结果数（默认值：100，最大值：1000）GIT_ENABLED：设置为“false”以禁用Git功能（默认值：“true”）GIT_AUTO_COMMIT：设置为“false”以禁用自动提交（默认值：“true”）GIT_USERNAME：Git提交的用户名（默认：“FileOps MCP”）GIT_EMAIL：Git提交的电子邮件（默认值：“fileops-mcp@no-reply.local")
命令行参数
# Run with specific options
uv run src/main.py --working-dir /path/to/dir --read-only --max-depth 3 --disable-auto-commit配置文件
使用您的设置创建JSON文件：
{
"working_dir": "/path/to/dir",
"read_only": true,
"hide_dot_files": true,
"max_depth": 3,
"max_results": 50,
"git_enabled": true,
"git_auto_commit": false,
"git_username": "Claude User",
"git_email": "claude@example.com"
}然后运行：
uv run src/main.py --config /path/to/config.json发展
欢迎投稿！要设置开发环境，请执行以下操作：
# Clone the repository
git clone https://github.com/yourusername/fileops-mcp.git
cd fileops-mcp
# Create a virtual environment
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest项目结构
fileops-mcp/
└── src/
├── __init__.py # Package initialization
├── main.py # Entry point and CLI
├── server.py # MCP server definition
├── constants.py # Configuration constants
├── operations/
│ ├── __init__.py
│ ├── file_ops.py # File operations
│ ├── dir_ops.py # Directory operations
│ ├── search_ops.py # Search operations
│ ├── version_ops.py # Git operations
│ ├── help_ops.py # Help operations
│ └── help_texts.py # Help text definitions
├── utils/
│ ├── __init__.py
│ ├── security.py # Security utilities
│ ├── path_utils.py # Path handling utilities
│ ├── git_utils.py # Git integration utilities
│ └── formatters.py # Output formatting utilities
└── resources/
├── __init__.py
└── resource_handlers.py # Resource endpoint handlers故障排除
- 权限错误：确保服务器可以访问指定的目录
- 不允许路径：检查路径是否在允许的目录内
- 二进制文件错误：只能读取或修改文本文件
- 文件大小限制：无法读取大于10MB的文件
- 搜索超时：对大型目录使用更具体的模式
- Git错误：确保安装了gitpython并且正确初始化了存储库
许可证
MIT许可证