内容
# 胡萝卜MCP
[](LICENSE)
各种硬件和数据接口的MCP（模型上下文协议）服务器集合。
## 安装
### uvx（无需安装，始终是最新的）
直接运行，无需安装。始终获取最新版本。
```bash
# 直接运行任意服务器
uvx carrot-mcp-pdf@latest
uvx carrot-mcp-io@latest
uvx carrot-mcp-nfc@latest
uvx carrot-mcp-office@latest
uvx carrot-mcp-sys@latest
# 通过元包运行
uvx carrot-mcp run pdf
```
### uv 工具（推荐）
持久安装，自动设置 PATH。升级干净。
```bash
# 安装所有
uv tool install carrot-mcp
# 安装特定服务器
uv tool install carrot-mcp[pdf]
uv tool install carrot-mcp[io]
uv tool install carrot-mcp[nfc]
uv tool install carrot-mcp[office]
uv tool install carrot-mcp[sys]
# 或直接安装子包
uv tool install carrot-mcp-pdf
uv tool install carrot-mcp-io
uv tool install carrot-mcp-nfc
uv tool install carrot-mcp-office
uv tool install carrot-mcp-sys
# 升级
uv tool upgrade carrot-mcp
# 卸载
uv tool uninstall carrot-mcp
```
### pip
经典 Python 安装。需要手动设置 PATH。
```bash
# 安装所有
pip install carrot-mcp
# 安装特定服务器
pip install carrot-mcp[pdf]
pip install carrot-mcp[io]
pip install carrot-mcp[nfc]
pip install carrot-mcp[office]
pip install carrot-mcp[sys]
# 或直接安装子包
pip install carrot-mcp-pdf
pip install carrot-mcp-io
pip install carrot-mcp-nfc
pip install carrot-mcp-office
pip install carrot-mcp-sys
# 升级
pip install --upgrade carrot-mcp
# 卸载
pip uninstall carrot-mcp
```
## 快速开始
### uvx（无需安装，始终是最新的）
```bash
# 直接运行特定服务器
uvx carrot-mcp-pdf@latest
uvx carrot-mcp-io@latest
uvx carrot-mcp-nfc@latest
uvx carrot-mcp-office@latest
uvx carrot-mcp-sys@latest
# 列出可用服务器
uvx carrot-mcp list
# 将所有 carrot 服务器添加到支持的代理
uvx carrot-mcp mcp add
# 强制使用 uvx 模式进行代理配置
uvx carrot-mcp mcp add --uvx
# 强制使用本地模式
uvx carrot-mcp mcp add --local
# 从代理中删除所有 carrot 服务器
uvx carrot-mcp mcp remove
```
### CLI（在 uv 工具或 pip 安装后）
```bash
# 列出所有可用服务器
carrot-mcp list
# 运行特定服务器
carrot-mcp run pdf
carrot-mcp run io
carrot-mcp run nfc
carrot-mcp run office
carrot-mcp run sys
# 将所有 carrot 服务器添加到支持的代理
carrot-mcp mcp add
# 添加到特定代理
carrot-mcp mcp add claude
carrot-mcp mcp add claude mimocode
# 强制使用 uvx 模式（自动更新）
carrot-mcp mcp add --uvx
# 强制使用本地模式
carrot-mcp mcp add --local
# 从代理中删除所有 carrot 服务器
carrot-mcp mcp remove
# 从特定代理中删除
carrot-mcp mcp remove claude
# 使用 uv 运行
uv run carrot-mcp run office
```
### Python 模块
```bash
python -m carrot_mcp_pdf
python -m carrot_mcp_io
python -m carrot_mcp_nfc
python -m carrot_mcp_office
python -m carrot_mcp_sys
```
## 可用服务器
| 服务器 | 包 | 类别 | 描述 |
|--------|---------|----------|-------------|
| PDF | `carrot-mcp-pdf` | 文档 | PDF 处理 |
| Office | `carrot-mcp-office` | 文档 | Excel 和 Word 自动化，自动备份 |
| IO | `carrot-mcp-io` | 硬件 | 串行、TCP、UDP 通信 |
| NFC | `carrot-mcp-nfc` | 硬件 | NFC 读取器（PN532，CLRC663） |
| SYS | `carrot-mcp-sys` | 系统 | 多模态分析的截图捕获 |
## 文档服务器
### PDF MCP 工具
| 工具 | 描述 |
|------|-------------|
| `version` | 获取服务器版本信息 |
| `get_toc` | 获取目录和页码范围 |
| `get_pages` | 将特定页面转换为 Markdown（支持多模态/OCR/强制 OCR） |
| `grep` | 在 PDF 页面中搜索精确的子字符串（不区分大小写，支持正则表达式） |
**环境变量：**
| 变量 | 描述 |
|----------|-------------|
| `CARROT_MCP_MODEL` | 视觉模型名称（如果使用 OCR，则必填） |
| `CARROT_MCP_APIKEY` | 视觉模型的 API 密钥 |
| `CARROT_MCP_PROXY` | API 调用的 HTTP 代理 URL |
| `CARROT_MCP_FORCE_MULTIMODAL` | `true` = 始终返回图像；`false` = 始终运行 OCR |
### Office MCP 工具
| 工具 | 描述 |
|------|-------------|
| `version` | 获取服务器版本信息和备份配置 |
#### Excel 工具
| 工具 | 描述 |
|------|-------------|
| `workbook_metadata` | 获取工作簿元数据（工作表名称，属性） |
| `workbook_grep` | 在单元格值中搜索精确的子字符串（不区分大小写，支持正则表达式） |
| `create_sheet` | 创建新的工作表（如果需要，创建工作簿） |
| `rename_sheet` | 重命名工作表 |
| `delete_sheet` | 删除工作表 |
| `insert_rows` | 在工作表中插入行 |
| `delete_rows` | 从工作表中删除行 |
| `insert_columns` | 在工作表中插入列 |
| `delete_columns` | 从工作表中删除列 |
| `read_range` | 从范围中读取单元格值 |
| `write_range` | 将 2D 数组写入范围（支持公式） |
| `copy_range` | 将范围复制到另一个位置 |
| `delete_range` | 清除范围内的单元格内容 |
| `read_chart` | 读取工作表中的图表信息 |
| `write_chart` | 创建图表（条形图，折线图，饼图，散点图） |
| `format_range` | 格式化单元格（字体，颜色，对齐方式，合并/拆分） |
#### Word 工具
| 工具 | 描述 |
|------|-------------|
| `inspect` | 检查文档结构（段落，表格，图像） |
| `get_outline` | 获取文档大纲为树形 + 平面列表 |
| `get_content` | 按章节或段落索引获取段落，表格和图像 |
| `get_table` | 读取表格内容为 2D 数组 |
| `grep` | 在段落中搜索精确的子字符串（不区分大小写，支持正则表达式） |
| `insert_para` | 插入段落 |
| `modify_para` | 修改段落文本 |
| `format_para` | 格式化段落（样式，对齐方式，字体） |
| `delete_para` | 删除段落 |
| `insert_table` | 插入表格，附带可选数据 |
| `modify_table` | 修改表格单元格 |
| `format_table` | 应用表格样式 |
| `delete_table` | 删除表格 |
| `insert_image` | 插入图像 |
| `delete_image` | 删除内联图像 |
#### 备份工具
| 工具 | 描述 |
|------|-------------|
| `backup_history` | 列出文件的所有备份版本 |
| `backup_restore` | 将文件恢复到特定的备份版本 |
功能：
- **自动备份**：所有修改都会自动版本化
- **旧格式支持**：`.doc` → `.docx`，`.xls` → `.xlsx` 通过 win32com（Windows）
- **100 版本限制**：每个文件 14 天过期
**环境变量：**
| 变量 | 描述 |
|----------|-------------|
| `CARROT_MCP_BACKUP_MAX_VERSIONS` | 每个文件的最大备份版本（默认：100） |
| `CARROT_MCP_BACKUP_MAX_AGE_DAYS` | 备份过期前的天数（默认：14） |
| `CARROT_MCP_BACKUP_ROOT` | 自定义备份目录 |
## 硬件服务器
### IO MCP 工具
| 工具 | 描述 |
|------|-------------|
| `version` | 获取服务器版本信息 |
| `list_transports` | 列出可用的传输类型和串行端口 |
| `open` | 打开连接（串行，TCP，UDP） |
| `close` | 关闭连接 |
| `read` | 从缓冲区阻塞读取，带有超时 |
| `recv` | 从缓冲区非阻塞读取 |
| `write` | 写入数据（十六进制或 ASCII，支持转义） |
| `script` | 执行 I/O 操作序列（写入/读取/等待/刷新） |
| `history` | 获取连接的操作历史 |
### NFC MCP 工具
| 工具 | 描述 |
|------|-------------|
| `version` | 获取服务器版本信息 |
| `list_readers` | 列出可用的读取器类型和传输方式 |
| `connect` | 连接到 NFC 读取器 |
| `disconnect` | 从读取器断开连接 |
| `find` | 查找并激活 NFC 卡 |
| `transceive` | 与比特级控制进行原始帧交换 |
| `reqa` | ISO14443-A REQA |
| `wupa` | ISO14443-A WUPA |
| `halt` | ISO14443-A HALT |
| `select` | ISO14443-A SELECT |
| `anticoll` | ISO14443-A 防冲突 |
| `field_on` | 打开 RF 场 |
| `field_off` | 关闭 RF 场 |
| `script` | 执行 NFC 操作序列 |
| `trace_get` | 获取跟踪日志条目 |
| `trace_clear` | 清除跟踪日志缓冲区 |
### 系统 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `version` | 获取服务器版本信息 |
| `list_monitors` | 列出所有监视器及其坐标和分辨率 |
| `screenshot` | 捕获截图 - 支持监视器索引，区域坐标或所有监视器 |
## MCP 配置
### 自动配置（推荐）
```bash
carrot-mcp mcp add
```
这将所有服务器添加到支持的代理（claude，opencode，mimocode）。自动检测是否使用 `carrot-mcp run` 或 `uvx`，具体取决于已安装的内容。使用 `--uvx` 或 `--local` 进行覆盖。
### 手动配置
**Claude Desktop** (`~/.claude.json`)：
```json
{
"mcpServers": {
"carrot-pdf": {
"command": "carrot-mcp",
"args": ["run", "pdf"]
},
"carrot-office": {
"command": "carrot-mcp",
"args": ["run", "office"]
},
"carrot-io": {
"command": "carrot-mcp",
"args": ["run", "io"]
},
"carrot-nfc": {
"command": "carrot-mcp",
"args": ["run", "nfc"]
},
"carrot-sys": {
"command": "carrot-mcp",
"args": ["run", "sys"]
}
}
}
```
**OpenCode / MiMoCode** (`~/.config/opencode/opencode.jsonc` 或 `~/.config/mimocode/mimocode.jsonc`)：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"carrot-pdf": {
"type": "local",
"command": ["carrot-mcp", "run", "pdf"],
"enabled": true,
"environment": {}
},
"carrot-office": {
"type": "local",
"command": ["carrot-mcp", "run", "office"],
"enabled": true,
"environment": {}
},
"carrot-io": {
"type": "local",
"command": ["carrot-mcp", "run", "io"],
"enabled": true,
"environment": {}
},
"carrot-nfc": {
"type": "local",
"command": ["carrot-mcp", "run", "nfc"],
"enabled": true,
"environment": {}
},
"carrot-sys": {
"type": "local",
"command": ["carrot-mcp", "run", "sys"],
"enabled": true,
"environment": {}
}
}
}
```
## 开发
```bash
# 克隆和设置
git clone <仓库 URL>
cd carrot-mcp
uv sync --all-packages
# 运行测试
uv run pytest
# 为特定服务器运行测试
uv run pytest tests/pdf/ -v
uv run pytest tests/office/ -v
uv run pytest tests/io/ -v
uv run pytest tests/nfc/ -v
uv run pytest tests/sys/ -v
# 升级版本和发布
bump.bat # 交互式
bump.bat carrot-mcp-office # 直接包
```
## 许可证
Apache License 2.0 - 参见 [LICENSE](LICENSE) 获取详细信息。
