Skip to main content

Introduction

The Labellerr MCP Server provides 23 specialized tools categorized into 6 functional groups. Claude automatically selects and executes the appropriate tool based on your conversational prompt. Each tool is classified as Read-only or Write:
  • Read-only tools: Safely inspect and query workspace data without modifying any state.
  • Write tools: Create or update resources (e.g. templates, projects, datasets, exports). You can configure Claude to request explicit confirmation before write operations execute.
Privacy & Security Guarantee: Tools return only resource IDs, names, and short status updates. They never output API keys, passwords, cloud access secrets, or raw file contents into the chat.

All Tools at a Glance


System

health Read-only

Use this tool first to diagnose connection or authentication issues.
  • Inputs: None
  • Returns: Status (ok), MCP server version, tool_count (23), client ID, and currently signed-in user account.

Projects

project_list Read-only

Lists projects in the active workspace with ID, name, data type, and status (ready, processing, or failed).

search_projects Read-only

Finds projects whose name or data type contains the query string (case-insensitive).

project_get Read-only

Retrieves detailed configuration and current status of a specific project.

project_setup Write

Creates both the annotation template and the project in a single atomic call from a plain list of labels. Used whenever you say “Create a project for cats and dogs on this dataset”.
  • Returns: project_id and template_id.
All precondition checks execute before any resource is created; a rejected request never leaves an orphaned template behind. For complex question types (radio, dropdown, text input, boolean), use template_create followed by project_create.

project_create Write

Creates a project from a pre-existing annotation template and a ready dataset.
  • Returns: The new project_id.

project_update_rotation Write

Adjusts the number of labeling, review, and client-review passes assigned to each file in a project.

Datasets & Connections

dataset_list Read-only

Lists datasets filtered by data type and visibility scope.

dataset_get Read-only

Retrieves status (ready, processing, failed, or not_found) and total file count for a dataset.

list_connections Read-only

Lists saved cloud storage connections in reverse chronological order (newest first).
  • Returns: connection_id, name, provider, connection_type, and creation timestamp.

connect_cloud_source Read-only

Provides a secure link to Labellerr’s connection screen in the web app. Credentials are typed directly into the Labellerr console and never passed through Claude.
  • Returns:
    • url: Direct link to the Labellerr web app connection form.
    • steps: Step-by-step setup instructions.
    • next: Automated follow-up actions once you confirm the connection has been saved.

dataset_create Write

Creates a dataset by importing files from a saved S3/GCS connection or from a public Google Drive link.
  • Returns: dataset_id, initial status (typically processing), and a job_id for tracking via get_job_status.

Templates

list_templates Read-only

Lists existing annotation templates with their configured questions and label classes.

template_create Write

Creates an annotation template with questions, labeling shapes, and classification options.
Example Questions Payload
  • Returns: template_id.

Annotations

upload_preannotations Write

Uploads model predictions or existing ground truth as pre-annotations in standard COCO JSON format. Supports dry-run validation to test for missing files and category mismatches before writing.
  • Returns: A job_id tracking processing status.
  • Dry-run mode: Claude validates file names (detecting case discrepancies such as IMG_1.jpg vs IMG_1.JPG), category alignment, and coordinates before committing.
Image file names in the COCO file must match the dataset file names strictly, including letter case and extension. Pre-annotation file size limit is 25 MB.

upload_preannotations_async Write

Uploads large pre-annotation batches asynchronously without blocking the conversational thread, returning immediately with a task tracker.
  • Returns: job_id for tracking through get_job_status.

export_annotations Write

Initiates an asynchronous export job for project annotations.
  • Returns: export_id and job_id. Once completed, obtain the signed link via download_export.

check_export_status Read-only

Queries the status of one or more export jobs. When is_completed is true, a direct signed download_url is returned.

download_export Read-only

Generates a secure, temporary pre-signed download URL for a completed export bundle.

Jobs & Monitoring

get_job_status Read-only

Queries the status of any background job started by dataset_create, upload_preannotations, upload_preannotations_async, or export_annotations.
  • Returns:
    • status: running, succeeded, or failed.
    • error: Explanatory message when status is failed.
    • For pre-annotation uploads: specific files and label categories that were skipped or not applied.

Job ID Formats


monitor_active_operations Read-only

Lists all background operations currently in progress across datasets, exports, and pre-annotation jobs.
  • Inputs: None
  • Returns: List of active operations with operation ID, operation type, start time, elapsed duration, and status.

monitor_project_progress Read-only

Retrieves real-time progress metrics for an ongoing labeling project.
  • Returns: Total files, annotated files, files pending review, rejected files, accepted files, and overall completion percentage.

query_project_statistics Read-only

Retrieves detailed analytical breakdown and label frequency counts for a project.
  • Returns: Label occurrence distributions, class counts, bounding box counts, and average annotations per asset.

Operational Limits


Supported Data Types


Overview & Setup

Set up the connector in Claude and authenticate your account.

Connect S3, GCS & Drive

Secure data connections without credential exposure.

Workflows & Examples

Practical examples of chaining these tools into end-to-end automations.

Changelog

See all recent tools and enhancements.