Label Studio MCP Server

1# Label Studio MCP Server
2 
3## Overview
4 
5This project provides a Model Context Protocol (MCP) server that allows interaction with a [Label Studio](https://labelstud.io/) instance using the `label-studio-sdk`. It enables programmatic management of labeling projects, tasks, and predictions via natural language or structured calls from MCP clients. Using this MCP Server, you can make requests like: 
6 
7* "Create a project in label studio with this data ..." 
8* "How many tasks are labeled in my RAG review project?" 
9* "Add predictions for my tasks." 
10* "Update my labeling template to include a comment box." 
11 
12<img src="./static/example.png" alt="Example usage of Label Studio MCP Server" width="600">
13 
14## Features
15 
16*   **Project Management**: Create, update, list, and view details/configurations of Label Studio projects.
17*   **Task Management**: Import tasks from files, list tasks within projects, and retrieve task data/annotations.
18*   **Prediction Integration**: Add model predictions to specific tasks.
19*   **SDK Integration**: Leverages the official `label-studio-sdk` for communication.
20 
21## Prerequisites
22 
231.  **Running Label Studio Instance:** You need a running instance of Label Studio accessible from where this MCP server will run.
242.  **API Key:** Obtain an API key from your user account settings in Label Studio.
25 
26## Configuration
27 
28The MCP server requires [the URL and API key for your Label Studio instance](https://labelstud.io/guide/access_tokens). If launching the server via an MCP client configuration file, you can specify the environment variables directly within the server definition. This is often preferred for client-managed servers.
29 
30Add the following JSON entry to your `claude_desktop_config.json` file or Cursor MCP settings:
31 
32```json
33{
34    "mcpServers": {
35        "label-studio": {
36            "command": "uvx",
37            "args": [
38                "--from",
39                "git+https://github.com/HumanSignal/label-studio-mcp-server",
40                "mcp-label-studio"
41            ],
42            "env": {
43                "LABEL_STUDIO_API_KEY": "your_actual_api_key_here", // <-- Your API key
44                "LABEL_STUDIO_URL": "http://localhost:8080"
45            }
46        }
47    }
48}
49```
50<!-- 
51## Installation
52Follow these instructions to install the server. 
53```bash
54git clone https://github.com/HumanSignal/label-studio-mcp-server.git 
55cd label-studio-mcp-server
56 
57# Install dependencies using uv
58uv venv
59source .venv/bin/activate 
60uv sync
61```
62 
63 
64    ```json
65    {
66      "mcpServers": {
67        "label-studio": {
68            "command": "uv",
69            "args": [
70                "--directory",
71                "/path/to/your/label-studio-mcp-server", // <-- Update this path
72                "run",
73                "label-studio-mcp.py"
74            ],
75            "env": {
76                "LABEL_STUDIO_API_KEY": "your_actual_api_key_here", // <-- Your API key
77                "LABEL_STUDIO_URL": "http://localhost:8080"
78            }
79        }
80      }
81    }
82    ```
83    When configured this way, the `env` block injects the variables into the server process environment, and the script's `os.getenv()` calls will pick them up. -->
84 
85## Tools
86 
87The MCP server exposes the following tools:
88 
89### Project Management
90 
91*   **`get_label_studio_projects_tool()`**: Lists available projects (ID, title, task count).
92*   **`get_label_studio_project_details_tool(project_id: int)`**: Retrieves detailed information for a specific project.
93*   **`get_label_studio_project_config_tool(project_id: int)`**: Fetches the XML labeling configuration for a project.
94*   **`create_label_studio_project_tool(title: str, label_config: str, ...)`**: Creates a new project with a title, XML config, and optional settings. Returns project details including a URL.
95*   **`update_label_studio_project_config_tool(project_id: int, new_label_config: str)`**: Updates the XML labeling configuration for an existing project.
96 
97### Task Management
98 
99*   **`list_label_studio_project_tasks_tool(project_id: int)`**: Lists task IDs within a project (up to 100).
100*   **`get_label_studio_task_data_tool(project_id: int, task_id: int)`**: Retrieves the data payload for a specific task.
101*   **`get_label_studio_task_annotations_tool(project_id: int, task_id: int)`**: Fetches existing annotations for a specific task.
102*   **`import_label_studio_project_tasks_tool(project_id: int, tasks_file_path: str)`**: Imports tasks from a JSON file (containing a list of task objects) into a project. Returns import summary and project URL.
103 
104### Predictions
105 
106*   **`create_label_studio_prediction_tool(task_id: int, result: List[Dict[str, Any]], ...)`**: Creates a prediction for a specific task. Requires the prediction result as a list of dictionaries matching the Label Studio format. Optional `model_version` and `score`.
107 
108## Example Use Case
109 
1101.  Create a new project using `create_label_studio_project_tool`.
1112.  Prepare a JSON file (`tasks.json`) with task data.
1123.  Import tasks using `import_label_studio_project_tasks_tool`, providing the project ID from step 1 and the path to `tasks.json`.
1134.  List task IDs using `list_label_studio_project_tasks_tool`.
1145.  Get data for a specific task using `get_label_studio_task_data_tool`.
1156.  Generate a prediction result structure (list of dicts).
1167.  Add the prediction using `create_label_studio_prediction_tool`.
117 
118 
119 
120## Contact
121 
122For questions or support, reach out via [GitHub Issues](https://github.com/HumanSignal/label-studio-mcp-server/issues).
123