内容
# 本地工具 MCP 服务器
一个最小化的 MCP 服务器，提供文件系统工具，限定在一个单独的工作空间文件夹（默认为 `~/mcp-workspace`），并支持在其中运行 Python 脚本。
工具列表：
**文件系统**
- `列出目录` — 列出文件/文件夹
- `树形目录` — 递归目录列表
- `读取文件` — 读取文本文件
- `写入文件` — 写入/创建文本文件
- `追加文件` — 追加到文件
- `删除文件` — 删除文件
- `复制文件` — 复制文件
- `移动文件` — 移动/重命名文件或文件夹
- `创建目录` — 创建目录
- `删除目录` — 删除目录（可选递归）
- `文件信息` — 大小/时间戳/类型元数据
- `搜索文件` — 按 glob 模式查找文件（例如 `*.py`）
- `搜索文件内容` — 在文件内容中搜索子字符串
- `文件哈希` — 文件的 sha256/sha1/md5
- `压缩目录` / `解压文件` — 压缩和解压存档
**脚本 / shell**
- `运行 Python 脚本` — 运行 `.py` 文件，捕获 stdout/stderr
- `运行 shell 命令` — 运行任意 shell 命令（工作目录 = 工作空间根目录）
**Git**（对工作空间根目录作为仓库进行操作）
- `git 状态`, `git 差异`, `git 日志`, `git 添加提交`
**系统 / 实用工具**
- `系统信息` — 操作系统，Python 版本，工作空间路径
- `列出环境变量` — 环境变量（可选前缀过滤）
- `当前时间` — 当前本地日期/时间
文件系统工具被沙盒化到工作空间根目录，因此它们不能超出该目录。`运行 shell 命令` 和 `运行 Python 脚本` **未被沙盒化**，超出其工作目录 — shell 命令仍可以执行用户帐户可以执行的任何操作，因此仅在您信任的机器/帐户上运行此服务器，并在自动化流程中信任命令之前进行审查。
## 1. 安装依赖项
```bash
cd mcp-local-tools
python3 -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
pip install -r requirements.txt
```
## 2. 独立测试（可选）
```bash
mcp dev server.py
```
这将在您的浏览器中打开 MCP Inspector，以便您可以手动调用工具。
## 3. 连接到 Claude Desktop
编辑您的 Claude Desktop 配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
添加：
```json
{
"mcpServers": {
"本地工具": {
"命令": "/绝对路径/到/mcp-local-tools/.venv/bin/python",
"参数": ["/绝对路径/到/mcp-local-tools/server.py"]
}
}
}
```
重启 Claude Desktop。工具应该出现在 🔌 图标下。
## 4. 连接到 Claude Code
```bash
claude mcp add 本地工具 -- /绝对路径/到/mcp-local-tools/.venv/bin/python /绝对路径/到/mcp-local-tools/server.py
```
## 自定义
- 在 `server.py` 中更改 `ALLOWED_ROOT` 以指向不同的文件夹。
- 通过编写一个用 `@mcp.tool()` 装饰的函数来添加新工具 —
文档字符串成为模型看到的工具描述，类型提示定义了预期的参数。
