Labellerr MCP Server

A Model Context Protocol (MCP) server that provides a comprehensive interface to the Labellerr SDK for managing annotation projects, datasets, and monitoring operations through AI assistants like Claude Desktop and Cursor.

Features

• 🚀 Project Management - Create, list, update, and track annotation projects

• 📊 Dataset Management - Create datasets, upload files/folders, and query information

• 🏷️ Annotation Tools - Upload pre-annotations, export data, and download results

• 📈 Monitoring & Insights - Real-time progress tracking and system health monitoring

• 🔍 Query Capabilities - Search projects, get statistics, and analyze operations

22 specialized tools available across 5 categories to streamline your annotation workflow.

Related MCP server: my-mcp-server

Installation

Prerequisites

• Node.js 16 or higher

• npm or yarn

• Labellerr API credentials (API Key, API Secret, Client ID)

Setup

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

Edit .env and add your Labellerr credentials:

LABELLERR_API_KEY=your_api_key_here
LABELLERR_API_SECRET=your_api_secret_here
LABELLERR_CLIENT_ID=your_client_id_here

Getting Credentials: Contact Labellerr support or email support@labellerr.com to obtain your API credentials.

Configuration

Option 1: Using with Claude Desktop

Add to your Claude Desktop configuration file:

Location: ~/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"
      }
    }
  }
}

Important: Replace /absolute/path/to/ with the full path to your installation directory.

After configuration:

1. Restart Claude Desktop completely

2. The Labellerr tools will be available in your conversations

3. Ask Claude to list your projects or check system health

Option 2: Using with Cursor

Add to your Cursor MCP configuration file:

Location: ~/.cursor/mcp.json (macOS/Linux) or %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"
      }
    }
  }
}

Important: Replace /absolute/path/to/ with the full path to your installation directory.

After configuration:

1. Restart Cursor completely (Quit and reopen)

2. The Labellerr tools will be available in the AI assistant

3. Try asking: "List all my Labellerr projects"

Verifying Installation

Test the server is working:

# Start the server
npm start

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

You should see a JSON response listing all 22 available tools.

Usage

Starting the Server Standalone

# Production mode
npm start

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

Using with AI Assistants

Once configured with Claude Desktop or Cursor, you can interact naturally:

Project Management:

• "List all my Labellerr projects"

• "Create a new image classification project for product categorization"

• "What's the progress of project XYZ?"

Dataset Operations:

• "Upload images from /path/to/folder"

• "List all my datasets"

• "Create a new dataset for video annotation"

Monitoring:

• "Show me system health"

• "Check the progress of my active projects"

• "What operations have been performed?"

Exports:

• "Export annotations in COCO format"

• "Check status of export ABC123"

• "Download completed export"

Current Status

✅ Fully Working (21 tools)

• Project Management: List, get details, update rotation

• Dataset Management: Create, upload, list, query

• Annotation Operations: Upload pre-annotations, export, download

• Monitoring: Job status, progress, system health

• Query & Search: Statistics, history, search

⚠️ In Progress (1 tool)

• Project Creation - Implementation complete but encountering API 400 error during dataset creation

  • File upload to GCS: ✅ Implemented

  • Dataset creation: ⚠️ Getting 400 error

  • Template creation: ✅ Implemented

  • Project finalization: ✅ Implemented

  • See Issue #1 for details

Available Tools

The server provides 22 specialized tools:

📋 Project Management (4 tools)

• project_create - Create projects with annotation guidelines

• project_list - List all projects

• project_get - Get detailed project information

• project_update_rotation - Update rotation configuration

📊 Dataset Management (5 tools)

• dataset_create - Create new datasets

• dataset_upload_files - Upload individual files

• dataset_upload_folder - Upload entire folders

• dataset_list - List all datasets

• dataset_get - Get dataset information

🏷️ Annotation Operations (5 tools)

• annotation_upload_preannotations - Upload pre-annotations (sync)

• annotation_upload_preannotations_async - Upload pre-annotations (async)

• annotation_export - Create annotation export

• annotation_check_export_status - Check export status

• annotation_download_export - Get export download URL

📈 Monitoring & Analytics (4 tools)

• monitor_job_status - Monitor background job status

• monitor_project_progress - Track project progress

• monitor_active_operations - List active operations

• monitor_system_health - Check system health

🔍 Query & Search (4 tools)

• query_project_statistics - Get detailed project stats

• query_dataset_info - Get dataset information

• query_operation_history - View operation history

• query_search_projects - Search projects by name/type

For detailed parameters and examples, see the Full Tool Documentation below.

Supported Data Types

• image - JPEG, PNG, TIFF

• video - MP4

• audio - MP3, WAV

• document - PDF

• text - TXT

Annotation Types

• BoundingBox - Rectangle annotations for object detection

• polygon - Polygon shapes for segmentation

• dot - Point annotations

• radio - Single choice selection

• dropdown - Dropdown selection

• boolean - Yes/No selection

• input - Text input field

• select - Multiple choice selection

Export Formats

• json - Standard JSON format

• coco_json - COCO dataset format

• csv - Comma-separated values

• png - Image masks

Limits

• Maximum 2,500 files per folder upload

• Maximum 2.5 GB total folder size

• Batch processing: 15 MB per batch, 900 files max

Example Workflows

1. Create an Object Detection Project

{
  "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. Monitor Project Progress

Ask your AI assistant: "Show me the progress of my annotation projects"

The server will return:

• Total files

• Annotated count

• Reviewed count

• Completion percentage

3. Export Annotations

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

4. Search Projects

Ask: "Find all projects related to 'vehicle' or 'traffic'"

The server will search project names and return matching results.

Detailed Tool Reference

project_create

Create a new annotation project.

Parameters:

• project_name (string, required) - Name of the project

• dataset_name (string, required) - Name of the dataset

• data_type (string, required) - Type: image/video/audio/document/text

• created_by (string, required) - Creator's email

• annotation_guide (array, required) - Annotation questions/guidelines

• dataset_description (string, optional) - Dataset description

• folder_to_upload (string, optional) - Path to folder with files

• files_to_upload (array, optional) - Array of file paths

• rotation_config (object, optional) - Rotation configuration

• autolabel (boolean, optional) - Enable auto-labeling

project_list

List all projects for the client.

Returns: Array of projects with metadata

project_get

Get detailed information about a specific project.

Parameters:

• project_id (string, required) - ID of the project

project_update_rotation

Update rotation configuration for a project.

Parameters:

• project_id (string, required) - ID of the project

• rotation_config (object, required) - New rotation settings

dataset_create

Create a new dataset.

Parameters:

• dataset_name (string, required) - Name of the dataset

• data_type (string, required) - Type of data

• dataset_description (string, optional) - Description

dataset_upload_files

Upload individual files to a dataset.

Parameters:

• files (array, required) - Array of file paths

• data_type (string, required) - Type of data

dataset_upload_folder

Upload all files from a folder.

Parameters:

• folder_path (string, required) - Path to folder

• data_type (string, required) - Type of data

dataset_list

List all datasets (linked and unlinked).

Parameters:

• data_type (string, optional) - Filter by data type (default: "image")

dataset_get

Get detailed information about a dataset.

Parameters:

• dataset_id (string, required) - ID of the dataset

annotation_upload_preannotations

Upload pre-annotations (synchronous).

Parameters:

• project_id (string, required) - ID of the project

• annotation_format (string, required) - Format: json/coco_json/csv/png

• annotation_file (string, required) - Path to annotation file

annotation_upload_preannotations_async

Upload pre-annotations (asynchronous).

Parameters:

• Same as annotation_upload_preannotations

annotation_export

Create an export of project annotations.

Parameters:

• project_id (string, required) - ID of the project

• export_name (string, required) - Name for the export

• export_format (string, required) - Format for export

• statuses (array, required) - Statuses to include

• export_description (string, optional) - Description

annotation_check_export_status

Check the status of export jobs.

Parameters:

• project_id (string, required) - ID of the project

• export_ids (array, required) - Array of export IDs

annotation_download_export

Get download URL for a completed export.

Parameters:

• project_id (string, required) - ID of the project

• export_id (string, required) - ID of the export

monitor_job_status

Monitor the status of a background job.

Parameters:

• job_id (string, required) - ID of the job

monitor_project_progress

Get progress statistics for a project.

Parameters:

• project_id (string, required) - ID of the project

monitor_active_operations

List all active operations and their status.

Returns: List of active operations with timestamps

monitor_system_health

Check the health and status of the MCP server.

Returns: System status, connectivity, active projects count

query_project_statistics

Get detailed statistics for a project.

Parameters:

• project_id (string, required) - ID of the project

query_dataset_info

Get detailed information about a dataset.

Parameters:

• dataset_id (string, required) - ID of the dataset

query_operation_history

Query the history of operations performed.

Parameters:

• limit (number, optional) - Max number of operations (default: 10)

• status (string, optional) - Filter by status: success/failed/in_progress

query_search_projects

Search for projects by name or type.

Parameters:

• query (string, required) - Search query string

Troubleshooting

Server won't start

• Verify Node.js version (requires 16+)

• Check environment variables are set correctly

• Ensure port is not in use

Tools return errors

• Verify Labellerr API credentials are correct

• Check network connectivity

• Review operation history for error details

AI assistant can't find tools

• Verify configuration file path is correct

• Use absolute paths, not relative paths

• Restart the AI assistant completely after configuration

• Check that credentials are set in the config file

Debug Mode

Set LOG_LEVEL=debug in your .env file for detailed logging.

Development

Project Structure

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

Adding New Tools

1. Define the tool schema in src/tools/index.js

2. Implement the handler in src/index.js (handleCallTool method)

3. Add the client method in src/labellerr-client.js if needed

4. Update documentation

Resources

• Labellerr Documentation: docs.labellerr.com

• MCP Protocol: modelcontextprotocol.io

• Support Email: support@labellerr.com

• GitHub Issues: github.com/1sarthakbhardwaj/labellerr-mcp-server/issues

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ for the Labellerr community