Labellerr MCP Server

Labellerr MCP 服务器

](https://github.com/1sarthakbhardwaj/labellerr-mcp-server/blob/main/LICENSE)  ](https://nodejs.org)

一个模型上下文协议（MCP）服务器，它为Labellerr SDK提供了全面的接口，以便通过AI助手（如Claude Desktop和Cursor）来管理标注项目、数据集和监控操作。

特点/特性

• 🚀 项目管理 - 创建、列出、更新和跟踪标注项目
• 📊 数据集管理 - 创建数据集，上传文件/文件夹，并查询信息
• 🏷️ 注释工具 - 上传预标注数据，导出数据，下载结果
• 📈 监控与洞察 - 实时进度跟踪和系统健康状况监测
• 🔍 查询功能 - 搜索项目，获取统计数据，分析运营情况

22种专业工具 提供5大类别，简化您的标注工作流程。

安装

先决条件

• Node.js 16或更高版本
• npm 或 yarn
• Labellerr API凭据（API密钥、API密钥、客户端ID）

设置

1. 克隆仓库：

git clone https://github.com/1sarthakbhardwaj/labellerr-mcp-server.git
cd labellerr-mcp-server

1. 安装依赖项：

npm install

1. 配置环境变量：

cp .env.example .env

编辑 .env 并添加您的Labellerr凭据：

LABELLERR_API_KEY=your_api_key_here
LABELLERR_API_SECRET=your_api_secret_here
LABELLERR_CLIENT_ID=your_client_id_here

获取凭证： 请联系Labellerr支持团队或发送邮件至support@labellerr.com以获取您的API凭证。

配置

选项1：与Claude桌面版一起使用

在您的Claude桌面配置文件中添加：

位置： ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "labellerr": {
      "command": "node",
      "args": ["/absolute/path/to/labellerr-mcp-server/src/index.js"],
      "env": {
        "LABELLERR_API_KEY": "your_api_key",
        "LABELLERR_API_SECRET": "your_api_secret",
        "LABELLERR_CLIENT_ID": "your_client_id"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/ 包含您安装目录的完整路径。

配置后：

1. 完全重启Claude桌面版
2. Labellerr 工具将在您的对话中可用
3. 请Claude列出您的项目或检查系统健康状况

选项2：使用光标配合使用

在您的 Cursor MCP 配置文件中添加：

地点： ~/.cursor/mcp.json (macOS/Linux) 或 %APPDATA%\Cursor\mcp.json （Windows）

{
  "mcpServers": {
    "labellerr": {
      "command": "node",
      "args": ["/absolute/path/to/labellerr-mcp-server/src/index.js"],
      "env": {
        "LABELLERR_API_KEY": "your_api_key",
        "LABELLERR_API_SECRET": "your_api_secret",
        "LABELLERR_CLIENT_ID": "your_client_id"
      }
    }
  }
}

重要提示： 替换 /absolute/path/to/ 加上您的安装目录的完整路径。

配置后：

1. 完全重启光标（退出并重新打开）
2. Labellerr 工具将在 AI 助手中可用
3. 尝试询问：“列出我所有的Labellerr项目”

验证安装

测试服务器是否正常运行：

# Start the server
npm start

# In another terminal, test the protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node src/index.js

你应该会看到一个JSON响应，其中列出了所有22个可用的工具。

使用

启动独立服务器

# Production mode
npm start

# Development mode (with auto-reload)
npm run dev

与AI助手一起使用

一旦通过Claude Desktop或Cursor进行配置，您就可以进行自然交互：

项目管理：

• “列出我所有的Labellerr项目”
• “为产品分类创建一个新的图像分类项目”
• “XYZ项目的进展如何？”

数据集操作：

• “从 /path/to/folder 上传图片”
• “列出我的所有数据集”
• “创建一个用于视频标注的新数据集”

监控：

• “显示系统健康状况”
• “查看我正在进行的项目的进度”
• “进行了哪些操作？”

出口：

• “以COCO格式导出注释”
• “检查出口ABC123的状态”
• “下载完成导出”

当前状态

✅ 完全可用（21种工具）

• 项目管理：列出、获取详情、更新轮换
• 数据集管理：创建、上传、列出、查询
• 注释操作：上传预注释、导出、下载
• 监控：作业状态、进度、系统健康状况
• 查询与搜索：统计、历史、搜索

⚠️ 进行中（1个工具）

• 项目创建 数据集创建过程中实现已完成，但遇到API 400错误

- 文件上传到GCS：✅ 已实现 - 数据集创建：⚠️ 收到400错误 - 模板创建：✅ 已实现 - 项目最终确定：✅ 已实施 - 见 问题#1 详情如下

可用工具

服务器提供了22种专业工具：

📋 项目管理（4种工具）

• project_create - 创建带有标注指南的项目
• project_list - 列出所有项目
• project_get - 获取详细的项目信息
• project_update_rotation - 更新轮换配置

📊 数据集管理（5种工具）

• dataset_create - 创建新数据集
• dataset_upload_files - 上传单个文件
• dataset_upload_folder - 上传整个文件夹
• dataset_list - 列出所有数据集
• dataset_get - 获取数据集信息

🏷️ 标注操作（5种工具）

• annotation_upload_preannotations - 上传预标注（同步）
• annotation_upload_preannotations_async - 上传预标注（异步）
• annotation_export - 创建注释导出
• annotation_check_export_status - 检查导出状态
• annotation_download_export - 获取导出下载URL

📈 监控与分析（4种工具）

• monitor_job_status - 监控后台作业状态
• monitor_project_progress - 跟踪项目进度
• monitor_active_operations - 列出活动操作
• monitor_system_health - 检查系统健康状况

🔍 查询与搜索（4种工具）

• query_project_statistics - 获取详细的项目统计数据
• query_dataset_info - 获取数据集信息
• query_operation_history - 查看操作历史
• query_search_projects - 按名称/类型搜索项目

如需详细的参数和示例，请参阅 完整的工具文档 在......下面

支持的数据类型

• 图像 - JPEG，PNG，TIFF
• 视频 - MP4（一种视频文件格式）
• 音频 - MP3，WAV
• 文件 - PDF（便携式文档格式）
• 文本 - 文本文件（TXT）

注解类型

• BoundingBox - 用于目标检测的矩形标注
• polygon - 用于分割的多边形形状
• dot - 点标注
• radio - 单选选择
• dropdown - 下拉选择
• boolean - 是/否选择
• input - 文本输入框
• select - 多选题选择

导出格式

• json - 标准JSON格式
• coco_json - COCO数据集格式
• csv - 逗号分隔值
• png - 图像遮罩

限制

• 每个文件夹最多可上传2,500个文件
• 文件夹总大小最大为2.5 GB
• 批处理：每批15 MB，最多900个文件

示例工作流程

1. 创建一个目标检测项目

{
  "project_name": "Vehicle Detection",
  "dataset_name": "Traffic Dataset",
  "data_type": "image",
  "created_by": "user@example.com",
  "annotation_guide": [
    {
      "question": "Detect Vehicles",
      "option_type": "BoundingBox",
      "required": true,
      "options": [{"option_name": "#ff0000"}]
    }
  ],
  "folder_to_upload": "/path/to/images"
}

2. 监控项目进度

询问你的AI助手：“展示我标注项目的进度”

服务器将返回：

• 总文件数
• 注释计数
• 审核数量
• 完成百分比

3. 导出注释

{
  "project_id": "proj_abc123",
  "export_name": "Training Export",
  "export_format": "coco_json",
  "statuses": ["accepted", "reviewed"]
}

4. 搜索项目

询问：“查找所有与‘车辆’或‘交通’相关的项目”

服务器将搜索项目名称并返回匹配结果。

详细工具参考

Project Management Tools

项目创建

创建一个新的标注项目。

参数：

• project_name （字符串，必填）- 项目名称
• dataset_name (字符串，必填) - 数据集名称
• data_type （字符串，必填）- 类型：图片/视频/音频/文档/文本
• created_by （字符串，必填）- 创建者的电子邮件
• annotation_guide (数组，必需) - 注解问题/指南
• dataset_description （字符串，可选）- 数据集描述
• folder_to_upload (字符串，可选) - 包含文件的文件夹路径
• files_to_upload (数组，可选) - 文件路径的数组
• rotation_config (对象，可选) - 旋转配置
• autolabel (布尔值，可选) - 启用自动标注

项目列表

列出所有为该客户做的项目。

返回值： 带有元数据的项目数组

获取项目

获取特定项目的详细信息。

参数：

• project_id (字符串，必填) - 项目的ID

项目更新轮换

更新项目的轮换配置。

参数：

• project_id (字符串，必填) - 项目的ID
• rotation_config (对象，必需) - 新的旋转设置

Dataset Management Tools

数据集创建

创建一个新的数据集。

参数：

• dataset_name (字符串，必填) - 数据集的名称
• data_type (字符串，必填) - 数据类型
• dataset_description (字符串，可选) - 描述

数据集上传文件

将单个文件上传到数据集中。

参数：

• files (数组，必需) - 文件路径的数组
• data_type (字符串，必填) - 数据类型

数据集上传文件夹

上传文件夹中的所有文件。

参数：

• folder_path (字符串，必填) - 文件夹路径
• data_type （字符串，必填）- 数据类型

数据集列表

列出所有数据集（包括链接和未链接的数据集）。

参数：

• data_type (字符串，可选) - 按数据类型过滤（默认：“图像”）

\dataset_get\ 翻译成中文是“获取数据集”

获取数据集的详细信息。

参数：

• dataset_id （字符串，必填）- 数据集的ID

Annotation Tools

上传预注释的注释

上传预标注（同步）。

参数：

• project_id (字符串，必填) - 项目ID
• annotation_format (字符串，必填) - 格式：json/coco_json/csv/png
• annotation_file (字符串，必需) - 注解文件的路径

异步上传预注释（用于标注上传）

上传预标注（异步）。

参数：

• 与……相同 annotation_upload_preannotations

注释导出

导出项目注释。

参数：

• project_id (字符串，必填) - 项目ID
• export_name (字符串，必填) - 导出的名称
• export_format (字符串，必填) - 导出格式
• statuses (数组，必需) - 要包含的状态
• export_description （字符串，可选）- 描述

注释检查导出状态

检查导出作业的状态。

参数：

• project_id (字符串，必填) - 项目ID
• export_ids (数组，必需) - 导出ID的数组

注释下载导出

获取已完成导出的下载URL。

参数：

• project_id (字符串，必填) - 项目ID
• export_id (字符串，必填) - 导出的ID

Monitoring Tools

监控作业状态

监控后台作业的状态。

参数：

• job_id （字符串，必填）- 作业的ID

监控项目进度

获取项目的进度统计信息。

参数：

• project_id （字符串，必填）- 项目ID

监控活跃操作

列出所有正在进行的操作及其状态。

返回值： 带有时间戳的活跃操作列表

监控系统健康状况

检查MCP服务器的健康状况和状态。

返回值： 系统状态、连接性、活跃项目数量

Query Tools

查询项目统计信息

获取项目的详细统计数据。

参数：

• project_id (字符串，必填) - 项目ID

查询数据集信息

获取有关数据集的详细信息。

参数：

• dataset_id （字符串，必填）- 数据集的ID

查询操作历史

查询已执行操作的历史记录。

参数：

• limit (数字，可选) - 最大操作数（默认：10）
• status （字符串，可选）- 按状态过滤：成功/失败/进行中

查询搜索项目

按名称或类型搜索项目。

参数：

• query (字符串，必填) - 搜索查询字符串

故障排除

服务器无法启动

• 验证 Node.js 版本（要求 16+）
• 检查环境变量是否设置正确
• 确保端口未被占用

工具返回错误

• 验证Labellerr API凭证是否正确
• 检查网络连接
• 查看操作历史记录以获取错误详情

AI助手找不到工具

• 验证配置文件路径是否正确
• 使用绝对路径，而非相对路径
• 配置完成后，完全重启AI助手
• 检查配置文件中是否已设置凭据

调试模式

设置 LOG_LEVEL=debug 在你的 .env 文件用于详细记录。

发展

项目结构

labellerr-mcp-server/
├── src/
│   ├── index.js              # Main server entry point
│   ├── labellerr-client.js   # Labellerr API client
│   └── tools/
│       └── index.js          # Tool definitions
├── package.json              # Dependencies and scripts
├── .env.example              # Environment template
├── claude_desktop_config.json # Claude configuration example
├── LICENSE                   # MIT License
└── README.md                 # This file

添加新工具

1. 定义工具模式（或工具架构）于 src/tools/index.js
2. 在（相应位置）实现处理程序 src/index.js (处理调用工具方法)
3. 在其中添加客户端方法 src/labellerr-client.js 如有需要
4. 更新文档

资源

• Labellerr 文档： docs.labellerr.com 翻译为中文可以是：“Labelr 文档网站”或“Labelr 的文档中心”，具体翻译可能根据上下文或品牌的具体含义有所调整
• MCP协议： modelcontextprotocol.io
• 支持邮箱： support@labellerr.com（邮箱地址，可直接翻译为“support@labellerr.com”，在中文语境中，通常直接使用原英文形式，无需额外翻译）
• GitHub Issues（问题追踪）：

许可证

MIT 许可证 - 详见 许可证 详情请查阅文件。

做出贡献

欢迎贡献！请随时提交拉取请求。

______________________________________________________________________

为Labellerr社区用心打造