使用说明

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-only

pip替代品

# 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.main

Claude桌面配置

编辑 ~/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许可证

使用说明

FileOps MCP服务器

概述

特性

资源

工具

安装和设置

UV快速入门

pip替代品

Claude桌面配置

使用MCP CLI进行安装

使用示例

在克劳德桌面

Git集成功能

配置选项

环境变量

命令行参数

配置文件

发展

项目结构

故障排除

许可证

相关 MCP

MySQL查询服务器

文件与终端管理MCP服务

Git仓库管理MCP服务器

Qdrant向量搜索MCP服务器

GitLab项目管理服务器

Shell与编码MCP服务器