roboflow-mcp

A Model Context Protocol (MCP) server that exposes the Roboflow platform API as tools in Claude Code. Manage datasets, trigger training runs, search Universe, and run inference — all from the CLI.

Setup

Requirements: Python 3.10+, a Roboflow API key, Claude Code installed.

git clone https://github.com/nickedridge-wq/roboflow-mcp.git
cd roboflow-mcp
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure Claude Code

Option A — project-level (recommended, checked into the repo):

claude mcp add roboflow \
  --env ROBOFLOW_API_KEY=your_api_key_here \
  -- /path/to/roboflow-mcp/venv/bin/python /path/to/roboflow-mcp/server.py

This writes a .mcp.json file in the current project directory.

Option B — user-level (available in all projects):

claude mcp add roboflow --scope user \
  --env ROBOFLOW_API_KEY=your_api_key_here \
  -- /path/to/roboflow-mcp/venv/bin/python /path/to/roboflow-mcp/server.py

Restart Claude Code — the mcp__roboflow__* tools will be available immediately.

Tools

Tool	Description
`list_workspaces`	Show workspace name, URL slug, and project count
`list_projects`	List all projects in a workspace with type and image counts
`get_project`	Get classes, annotation type, and metadata for a project
`list_versions`	List all dataset versions with image counts per split
`upload_image`	Upload an image and optional annotation to a project
`create_version`	Generate a new dataset version with preprocessing and augmentation
`download_dataset`	Download a version locally (yolov8, coco, voc, and more)
`download_universe_dataset`	Download a public dataset directly from Roboflow Universe
`search_universe`	Search Universe for public datasets and pre-trained models
`run_inference`	Run inference via a deployed model on a local file or URL
`get_model_metrics`	Fetch mAP, precision, and recall for a trained version

Example Workflows

Find and download a public dataset

search_universe("hard hat detection")
→ pick a result, note workspace + project + version

download_universe_dataset(
  universe_workspace="roboflow-universe-projects",
  universe_project="hard-hat-universe",
  version_number=1,
  model_format="yolov8",
  location="./datasets/hard-hat"
)

Upload images and generate a training version

upload_image(project_url="my-project", image_path="/data/img001.jpg",
             annotation_path="/data/img001.xml", split="train")

create_version(
  project_url="my-project",
  preprocessing={"auto-orient": True, "resize": {"width": 640, "height": 640, "format": "Stretch to"}},
  augmentation={"flip": {"horizontal": True}, "rotation": {"degrees": 15}}
)

Run inference and check model performance

run_inference(project_url="my-project", version_number=3,
              image_path="/data/test.jpg", confidence=60)

get_model_metrics(project_url="my-project", version_number=3)

Tests

python -m unittest test_server -v

21 tests covering output suppression, lazy init thread safety, input validation, null model guard, auth error propagation, and parameter contracts. No live API key required.

Implementation Notes

Lazy authentication — the Roboflow SDK authenticates once per session on first tool call, with double-checked locking for thread safety.
Output suppression — the SDK prints to both stdout and stderr on init, which corrupts MCP's stdio transport. All SDK calls redirect both streams.
search_universe and get_model_metrics call the Roboflow REST API directly for endpoints not exposed cleanly through the SDK.

Roboflow MCP Server