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.
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 theSDKPython repository and install the necessary dependencies:
Clone & Install
Configuration
Configure your AI assistant with the absolute path toserver.py and your API credentials.
- Cursor
- Claude Desktop
- Claude Code
Add the configuration to
~/.cursor/mcp.json:Cursor Configuration
Available Tools
The local server provides 23 comprehensive tools organized into 5 categories:Project Management (4 tools)
Project Management (4 tools)
project_create: Create a new annotation project (requiresdataset_idandtemplate_id)project_list: List all projects in your workspaceproject_get: Retrieve detailed information about a specific projectproject_update_rotation: Update annotation, review, and client-review rotation counts
Dataset Management (5 tools)
Dataset Management (5 tools)
dataset_create: Create dataset with automatic file upload and status pollingdataset_upload_files: Upload individual files to create a datasetdataset_upload_folder: Upload an entire local directory of filesdataset_list: List all datasets with filtering optionsdataset_get: Get detailed information and file counts for a dataset
Annotation Operations (6 tools)
Annotation Operations (6 tools)
template_create: Create annotation template with questions and guidelinesannotation_export: Export project annotations in JSON, COCO, CSV, or PNGannotation_check_export_status: Check status of export jobsannotation_download_export: Get download URL for completed exportsannotation_upload_preannotations: Upload pre-annotations (synchronous)annotation_upload_preannotations_async: Upload pre-annotations (asynchronous)
Monitoring Tools (4 tools)
Monitoring Tools (4 tools)
monitor_system_health: Check MCP server health and connection statusmonitor_active_operations: List all active operations and their statusmonitor_project_progress: Get progress statistics for a projectmonitor_job_status: Monitor background job status
Query Tools (4 tools)
Query Tools (4 tools)
query_project_statistics: Get detailed statistics for a projectquery_dataset_info: Get detailed information about a datasetquery_operation_history: Query history of operations performedquery_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
- Uploads all valid images from
/Users/me/products - Creates and indexes a new dataset
- Generates the annotation template with bounding box questions
- Creates and links the project ready for labeling
Monitor Project Progress
Prompt
Export Annotations
Prompt
Upload Additional Data
Prompt
Troubleshooting
AI assistant doesn't show tools
AI assistant doesn't show tools
- Restart your AI assistant completely (quit and reopen application).
- Ensure the path to
server.pyis absolute (starts with/on macOS/Linux orC:\on Windows). - Manually test the server script:
python3 /path/to/server.py. - Check JSON configuration syntax (commas, unescaped slashes, quotes).
Authentication errors
Authentication errors
- Verify your
LABELLERR_API_KEY,LABELLERR_API_SECRET, andLABELLERR_CLIENT_IDare valid in your Labellerr workspace settings. - Confirm all three environment variables are present in the config file.
- Completely restart the assistant after editing credentials.
File upload issues
File upload issues
- 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.

