Skip to main content
Glama
Labellerr MCP Server

Labellerr MCP Server

Labellerr MCP Server

GitHub license MCP Protocol Node.js

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
  1. Install dependencies:

npm install
  1. 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

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

Available Tools

22 tools
annotation_check_export_statusC

Check the status of export jobs

Inputs: export_ids (required), project_id (required).

annotation_download_exportA

Get download URL for a completed export

Inputs: export_id (required), project_id (required).

annotation_exportC

Create an export of project annotations

Inputs: statuses (required), project_id (required), export_name (required), export_format (required), +1 more.

annotation_upload_preannotationsA

Upload pre-annotations to a project (synchronous)

Inputs: project_id (required), annotation_file (required), annotation_format (required).

annotation_upload_preannotations_asyncB

Upload pre-annotations to a project (asynchronous)

Inputs: project_id (required), annotation_file (required), annotation_format (required).

dataset_createB

Create a new dataset

Inputs: data_type (required), dataset_name (required), dataset_description.

dataset_getC

Get detailed information about a dataset

Inputs: dataset_id (required).

dataset_listA

List all datasets (linked and unlinked)

Inputs: data_type.

dataset_upload_filesC

Upload individual files to a dataset

Inputs: files (required), data_type (required).

dataset_upload_folderB

Upload all files from a folder to a dataset

Inputs: data_type (required), folder_path (required).

monitor_active_operationsA

List all active operations and their status

Inputs: no named parameters.

monitor_job_statusC

Monitor the status of a background job

Inputs: job_id (required).

monitor_project_progressC

Get progress statistics for a project

Inputs: project_id (required).

monitor_system_healthA

Check the health and status of the MCP server

Inputs: no named parameters.

project_createB

Create a new annotation project with dataset and guidelines

Inputs: data_type (required), created_by (required), dataset_name (required), project_name (required), +6 more.

project_getA

Get detailed information about a specific project

Inputs: project_id (required).

project_listA

List all projects for the client

Inputs: no named parameters.

project_update_rotationB

Update rotation configuration for a project

Inputs: project_id (required), rotation_config (required).

query_dataset_infoC

Get detailed information about a dataset

Inputs: dataset_id (required).

query_operation_historyC

Query the history of operations performed

Inputs: limit, status.

query_project_statisticsC

Get detailed statistics for a project

Inputs: project_id (required).

query_search_projectsB

Search for projects by name or type

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 22 tools

    Disambiguation2/5

    Several tools have overlapping purposes: dataset_get and query_dataset_info both retrieve dataset details, while monitor_project_progress and query_project_statistics both provide project progress stats. project_list and query_search_projects also overlap in listing projects. This creates ambiguity for agents selecting the right tool.

    Naming Consistency3/5

    Naming is grouped by prefixes like project_, dataset_, annotation_, monitor_, query_, but the convention varies: some groups use resource_first (project_list, dataset_get) while others use action_first (monitor_job_status, query_project_statistics). Within each group it's consistent, but across groups the pattern is mixed, making it moderately predictable.

    Tool Count3/5

    With 22 tools, the count is on the heavier side. The scope covers projects, datasets, annotations, monitoring, and queries, so it isn't unreasonable, but it's borderline compared to the typical 3-15 tool range for a well-scoped server. Some tools are redundant, further padding the count.

    Completeness3/5

    The server covers core workflows for projects, datasets, and annotations, including creation, retrieval, uploading, and export. However, it lacks basic delete operations (e.g., no project delete or dataset delete) and has no annotation listing or detailed annotation viewing. The duplication of dataset info and project stats tools also suggests incomplete integration of the query and monitor groups.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.
      5
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
      -
    • A
      license
      B
      quality
      D
      maintenance
      A model context protocol server that enables applications to use stackzero-labs/ui components through the MCP protocol, supporting both standalone operation and integration with Claude Desktop and Cursor.
      12
      19 npm
      5
      MIT