Label Studio MCP Server for Labeling Automation

Overview

This MCP (Model Context Protocol) server connects an MCP-capable client (for example a generative assistant) to a running Label Studio instance using the official label-studio-sdk. It exposes programmatic operations for creating and managing Label Studio projects, importing and listing tasks, reading annotations, and attaching model predictions — all via structured calls or natural-language-driven requests routed through the MCP layer.

For teams automating labeling workflows, this server reduces manual work: you can spin up projects from templates, import bulk task files, query task/annotation status, and push model predictions back into Label Studio without writing bespoke API glue code. It is especially useful when integrating labeling operations into interactive assistants, pipelines, or developer tools that speak MCP.

See the project on GitHub: https://github.com/HumanSignal/label-studio-mcp-server

Features

• Project management: create, update, list, and inspect Label Studio projects and their configuration (label XML).
• Task management: import tasks from JSON, list task IDs, fetch task payloads and annotations.
• Prediction integration: add model predictions (results, model_version, score) to tasks.
• Uses the official label-studio-sdk for authenticated, supported API access.
• Designed for MCP clients: exposes tools that can be invoked programmatically or via natural-language agents.

Installation / Configuration

Prerequisites:

• A running Label Studio instance reachable from where the MCP server runs.
• A Label Studio API key (create one in Label Studio user settings).

Example: run locally inside a Python virtual environment (recommended).

Clone and set up:

git clone https://github.com/HumanSignal/label-studio-mcp-server.git
cd label-studio-mcp-server

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies (using pip)
pip install -r requirements.txt

Environment variables (required):

export LABEL_STUDIO_URL="http://localhost:8080"    # URL of your Label Studio instance
export LABEL_STUDIO_API_KEY="your_api_key_here"    # API key from Label Studio

Example MCP client configuration (JSON snippet) — client-managed server can inject env vars:

{
  "mcpServers": {
    "label-studio": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/HumanSignal/label-studio-mcp-server",
        "mcp-label-studio"
      ],
      "env": {
        "LABEL_STUDIO_API_KEY": "your_actual_api_key_here",
        "LABEL_STUDIO_URL": "http://localhost:8080"
      }
    }
  }
}

Start the MCP server (example):

# With virtualenv active, run the server module / script as provided in the repo:
python -m mcp_label_studio.server

(Adjust the module name/entrypoint to match the repository version you’re running.)

Available Tools

The MCP server exposes tools grouped by capability. Each tool returns JSON-like responses appropriate for programmatic consumption.

Project management:

• get_label_studio_projects_tool(): list projects (id, title, task_count).
• get_label_studio_project_details_tool(project_id: int): full project metadata.
• get_label_studio_project_config_tool(project_id: int): XML label configuration.
• create_label_studio_project_tool(title: str, label_config: str, …): create project, returns project details + URL.
• update_label_studio_project_config_tool(project_id: int, new_label_config: str): update XML template.

Task management:

• list_label_studio_project_tasks_tool(project_id: int): up to 100 task IDs.
• get_label_studio_task_data_tool(project_id: int, task_id: int): task payload/data.
• get_label_studio_task_annotations_tool(project_id: int, task_id: int): existing annotations for the task.
• import_label_studio_project_tasks_tool(project_id: int, tasks_file_path: str): import tasks from a JSON file (list of objects), returns import summary and project URL.

Predictions:

• create_label_studio_prediction_tool(task_id: int, result: List[Dict], model_version: str = None, score: float = None): attach a prediction to a task. Result must match Label Studio result schema.

Summary table

Use Cases

1. Create a project from an XML labeling config and import tasks

   • Call create_label_studio_project_tool with a title and label XML.
   • Prepare tasks.json (array of task objects):

     [
       {"data": {"image": "https://.../image1.jpg"}, "meta": {"source": "s3"}},
       {"data": {"image": "https://.../image2.jpg"}}
     ]
     

   • Call import_label_studio_project_tasks_tool(project_id, “/path/to/tasks.json”).
   • Use list_label_studio_project_tasks_tool to verify imported task IDs.

2. Read a task, run a model, and add a prediction

   • Use get_label_studio_task_data_tool(project_id, task_id) to get input.
   • Run your model to produce a Label Studio-compatible result list, for example:

     [
       {
         "from_name": "label",
         "to_name": "image",
         "type": "choices",
         "value": {"choices": ["cat"]}
       }
     ]
     

   • Call create_label_studio_prediction_tool(task_id, result, model_version=“v1”, score=0.92).

3. Inspect project configuration and adjust label XML

   • get_label_studio_project_config_tool(project_id) returns the current XML.
   • Modify the XML (e.g., add a comment box) and call update_label_studio_project_config_tool(project_id, new_xml).

Troubleshooting & Support

• Ensure LABEL_STUDIO_URL is reachable from the server environment.
• Verify the API key has necessary permissions to create projects and modify tasks.
• For bugs or feature requests, open an issue on the repository: https://github.com/HumanSignal/label-studio-mcp-server/issues

This MCP server is intended as a lightweight integration layer so assistants and automation scripts can operate Label Studio programmatically and consistently.