Skip to main content

Introduction

The Labellerr Local MCP Server runs locally on your workstation or server, communicating with AI assistants like Claude Desktop, Cursor, or Claude Code via standard input/output (stdio). It authenticates using your Labellerr API credentials and provides 23 tools, including direct support for uploading local files and directories from your hard drive.
Which one should you use? For most users and teams, the Hosted Connector is recommended: zero local installation, OAuth sign-in in the browser, and seamless support in Claude.ai (web). Choose the Local Server if you need to upload files directly from your local filesystem or use Cursor.

Quick Start

Prerequisites

  • Python 3.10 or higher
  • Git installed on your system
  • Labellerr API credentials (API Key, API Secret, Client ID) — Get credentials
  • Claude Desktop, Cursor, or Claude Code installed

Installation

Clone the SDKPython repository and install the necessary dependencies:
Clone & Install

Configuration

Configure your AI assistant with the absolute path to server.py and your API credentials.
Add the configuration to ~/.cursor/mcp.json:
Cursor Configuration
Important: Always provide the absolute path to server.py. Completely restart your AI assistant application after updating configuration files. Keep configuration files secure: your API secret grants full access to your Labellerr workspace.

Available Tools

The local server provides 23 comprehensive tools organized into 5 categories:
  • project_create: Create a new annotation project (requires dataset_id and template_id)
  • project_list: List all projects in your workspace
  • project_get: Retrieve detailed information about a specific project
  • project_update_rotation: Update annotation, review, and client-review rotation counts
  • dataset_create: Create dataset with automatic file upload and status polling
  • dataset_upload_files: Upload individual files to create a dataset
  • dataset_upload_folder: Upload an entire local directory of files
  • dataset_list: List all datasets with filtering options
  • dataset_get: Get detailed information and file counts for a dataset
  • template_create: Create annotation template with questions and guidelines
  • annotation_export: Export project annotations in JSON, COCO, CSV, or PNG
  • annotation_check_export_status: Check status of export jobs
  • annotation_download_export: Get download URL for completed exports
  • annotation_upload_preannotations: Upload pre-annotations (synchronous)
  • annotation_upload_preannotations_async: Upload pre-annotations (asynchronous)
  • monitor_system_health: Check MCP server health and connection status
  • monitor_active_operations: List all active operations and their status
  • monitor_project_progress: Get progress statistics for a project
  • monitor_job_status: Monitor background job status
  • query_project_statistics: Get detailed statistics for a project
  • query_dataset_info: Get detailed information about a dataset
  • query_operation_history: Query history of operations performed
  • query_search_projects: Search for projects by name or type

Local Server vs. Hosted Connector Tools

Both the Hosted Connector and Local Server provide 23 comprehensive tools tailored to their operating environments:

Usage Examples

Create a Complete Project from Local Files

Prompt
Automated execution:
  1. Uploads all valid images from /Users/me/products
  2. Creates and indexes a new dataset
  3. Generates the annotation template with bounding box questions
  4. Creates and links the project ready for labeling

Monitor Project Progress

Prompt

Export Annotations

Prompt

Upload Additional Data

Prompt

Troubleshooting

  • Restart your AI assistant completely (quit and reopen application).
  • Ensure the path to server.py is absolute (starts with / on macOS/Linux or C:\ on Windows).
  • Manually test the server script: python3 /path/to/server.py.
  • Check JSON configuration syntax (commas, unescaped slashes, quotes).
  • Verify your LABELLERR_API_KEY, LABELLERR_API_SECRET, and LABELLERR_CLIENT_ID are valid in your Labellerr workspace settings.
  • Confirm all three environment variables are present in the config file.
  • Completely restart the assistant after editing credentials.
  • Ensure file paths passed to the assistant are absolute, not relative.
  • Verify read permissions on the directory.
  • Confirm file formats match the specified data type (JPG, PNG, MP4, MP3, PDF, TXT).

Additional Resources

GitHub Repository

Source code and installation files for the Python SDK and MCP server.

Hosted Connector

Switch to the zero-install hosted connector for Claude.

SDK Documentation

Programmatic Python SDK documentation for custom automation scripts.

MCP Tools Reference

Reference documentation for hosted MCP tools.