Copick MCP Server

A Model Context Protocol (MCP) server for Copick that provides two sets of tools:

1. Data Exploration Tools - Browse and query copick project contents (read-only)
2. CLI Introspection Tools - Discover and validate copick CLI commands for building processing pipelines

Features

• Read-only data exploration - List and inspect runs, picks, segmentations, meshes, tomograms, and project metadata
• CLI discovery - Dynamically discover all available copick CLI commands with compact summaries and opt-in help
• Command validation - Validate copick CLI command syntax using Click's native parsing
• Smart caching - Bounded project-root caching that reloads changed configurations
• Easy setup - Simple CLI for registering with Claude Desktop or Claude Code

Installation

pip install copick-mcp

During the 2.0 prerelease series, opt in explicitly:

pip install --pre "copick-mcp>=2.0.0a1,<3"

The optional torch command integration is available with:

pip install "copick-mcp[torch]"

For the matching 2.0 prerelease stack, use pip install --pre "copick-mcp[torch]>=2.0.0a1,<3".

Copick 2.0 and Zarr compatibility

The copick-mcp 2.0 line requires Python 3.11 or newer, copick 2.0, and copick-utils 2.0. Its data-exploration tools use copick's entity and metadata APIs and therefore inherit support for the legacy and current project formats supported and tested by copick.

copick-mcp does not open arrays, interpret OME-Zarr layouts, or write project data. Its tests verify format-neutral entity discovery; they do not re-test OME-Zarr parsing. Format interoperability, output format, and storage-backend behavior are owned by copick and the command plugin being described. Installing the torch extra adds the copick-torch 2.0 command plugins and enables installed nnUNet workflow status; no model is loaded or executed by introspection.

Quick Setup

Register with Claude Desktop

Use the copick CLI to register the MCP server with Claude Desktop:

# Basic setup (default settings)
copick setup mcp

# Setup with custom server name
copick setup mcp --server-name "my-copick-server"

# Setup with default config path (optional - can be provided per-request)
copick setup mcp --config-path "/path/to/default/config.json"

# Check registration status
copick setup mcp-status

After setup:

1. Restart Claude Desktop completely
2. The Copick MCP tools should now be available
3. The server starts automatically when Claude Desktop connects

Register with Claude Code

The MCP server can also be registered with Claude Code, either globally or for a specific project:

# Global setup (available in all Claude Code sessions)
copick setup mcp --target code-global

# Project-specific setup (creates .mcp.json in current directory)
copick setup mcp --target code-project

# Project-specific setup for a different directory
copick setup mcp --target code-project --project-path /path/to/project

# Check status for Claude Code
copick setup mcp-status --target code-global
copick setup mcp-status --target code-project

Target options:

• desktop (default) - Claude Desktop application
• code-global - Claude Code global config (~/.claude.json)
• code-project - Claude Code project-specific config (.mcp.json in project root)

Manual Configuration (Optional)

If you prefer manual setup, add the following configuration to the appropriate file:

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code:

• Global: ~/.claude.json
• Project-specific: .mcp.json in your project root

{
  "mcpServers": {
    "copick-mcp": {
      "command": "python",
      "args": ["-m", "copick_mcp.main"],
      "env": {}
    }
  }
}

Available Tools

Data Exploration Tools (Read-Only)

Data exploration tools accept a config_path pointing to a Copick configuration file. It may be omitted when the server was registered with --config-path, which supplies COPICK_MCP_DEFAULT_CONFIG; an explicit path always wins.

list_runs

List all runs in a Copick project.

• Args: config_path (optional when a server default is configured)
• Returns: List of run names

get_run_details

Get detailed information about a specific run including voxel spacings, picks, meshes, and segmentations.

• Args: run_name (str), config_path (optional), include_point_details (optional, default false)
• Returns: Comprehensive run details

list_objects

List all pickable objects defined in the project.

• Args: config_path (optional when a server default is configured)
• Returns: List of objects with properties (name, type, label, color, radius, etc.)

list_picks

List picks for a run with optional filtering.

• Args: run_name (str), config_path (optional), object_name (optional), user_id (optional), session_id (optional), include_point_details (optional, default false)
• Returns: Pick metadata; opt-in details add point counts and sample coordinates, with per-pick load errors isolated

list_meshes

List meshes for a run with optional filtering.

• Args: run_name (str), config_path (optional), object_name (optional), user_id (optional), session_id (optional)
• Returns: List of meshes

list_segmentations

List segmentations for a run with optional filtering.

• Args: run_name (str), config_path (optional), voxel_size (optional), name (optional), user_id (optional), session_id (optional), is_multilabel (optional)
• Returns: List of segmentations with metadata

list_tomograms

List tomograms for a specific run and voxel spacing.

• Args: run_name (str), voxel_spacing (float), config_path (optional)
• Returns: List of tomograms with feature information

list_voxel_spacings

List all voxel spacings available for a run.

• Args: run_name (str), config_path (optional)
• Returns: List of voxel spacings with tomogram counts

get_project_info

Get general project information and statistics.

• Args: config_path (optional when a server default is configured)
• Returns: Project metadata and entity counts

get_json_config

Get the normalized, validated JSON configuration of the project.

• Args: config_path (optional when a server default is configured)
• Returns: Copick's JSON-serializable configuration model; non-Copick and oversized JSON files are rejected

CLI Introspection Tools

These tools help LLMs discover and validate copick CLI commands for building processing pipelines.

list_copick_cli_commands

List all available copick CLI commands hierarchically organized by group.

• Args: include_help (optional, default false); enable only when full help for every command is required
• Returns: Complete command tree including:
  • main: Core commands (add, browse, config, cp, deposit, export, info, mv, new, rm, stats, sync)
  • inference: Inference commands (e.g., membrain-seg)
  • training: Training commands
  • evaluation: Evaluation commands
  • process: Processing commands (downsample, fit-spline, hull, skeletonize, etc.)
  • convert: Conversion commands (picks2seg, mesh2seg, seg2picks, etc.)
  • logical: Logical operations (clipmesh, clippicks, meshop, segop, etc.)
  • setup: Integration commands, including copick-mcp registration
  • download: Download commands contributed by installed plugins

The plugin-group inventory comes from copick itself. Compatible future groups therefore appear in MCP discovery without a matching hardcoded list here.

get_copick_cli_command_info

Get detailed information about a specific command.

• Args: command_path (str) - e.g., "convert.picks2seg" or "add"
• Returns: Full command details including:
  • Help text and short description
  • All parameters with types, defaults, and help text
  • Required vs optional parameters
  • Usage examples (if present in help)
  • Command group

validate_copick_cli_command

Validate a copick CLI command string using Click's syntax validation.

• Args: command_string (str) - e.g., "copick convert picks2seg --config /path/to/config.json ..."
• Returns: Validation result including:
  • Valid/invalid status
  • Resolved command path for parameter errors
  • Missing required parameters
  • Parameter type errors
  • Helpful error messages from Click
  • Captured Click help or diagnostics in output, when applicable

get_nnunet_workflow_info

Return the prepare → train → inference workflow for copick-torch.

• Returns: Installation status, GPU safety guidance, and authoritative command parameters/help read from installed copick-torch entry points
• When the optional package is absent, returns installation instructions without duplicating a potentially stale parameter table

Usage Examples

Data Exploration Workflow

User: "Show me all runs in my copick project at /data/my_project/config.json"

Assistant uses: list_runs(config_path="/data/my_project/config.json")

User: "What picks are available for run TS_001?"

Assistant uses: list_picks(config_path="/data/my_project/config.json", run_name="TS_001")

User: "Show me only the ribosome picks from user 'annotator1'"

Assistant uses: list_picks(
    config_path="/data/my_project/config.json",
    run_name="TS_001",
    object_name="ribosome",
    user_id="annotator1"
)

CLI Discovery Workflow

User: "I want to convert picks to a segmentation. What copick command can do that?"

Assistant uses: list_copick_cli_commands()
# Discovers convert.picks2seg command

Assistant uses: get_copick_cli_command_info(command_path="convert.picks2seg")
# Gets full documentation and parameters
Assistant explains:
"The picks2seg command converts picks to segmentation by painting spheres at pick locations.
It requires:
- --config: Path to copick config
- --input: Picks URI (format: object_name:user_id/session_id)
- --output: Segmentation URI (format: name:user_id/session_id@voxel_spacing)
- --radius: Sphere radius in angstroms (default: 10.0)"

User: "Can you validate this command for me: copick convert picks2seg --config /data/config.json --input 'ribosome:user1/manual-001' --output 'ribosome:picks2seg/painted-001@10.0'"

Assistant uses: validate_copick_cli_command(
    command_string="copick convert picks2seg --config /data/config.json --input 'ribosome:user1/manual-001' --output 'ribosome:picks2seg/painted-001@10.0'"
)# Returns validation result: valid=True if syntax is correct

Pipeline Building Workflow

User: "I want to build a pipeline that:
1. Converts ribosome picks to meshes
2. Computes the convex hull of those meshes
3. Converts the hulls to segmentations"

Assistant uses: list_copick_cli_commands()
# Discovers relevant commands in convert and process groups

Assistant uses: get_copick_cli_command_info(command_path="convert.picks2mesh")
Assistant uses: get_copick_cli_command_info(command_path="process.hull")
Assistant uses: get_copick_cli_command_info(command_path="convert.mesh2seg")
# Gets documentation for each command

Assistant suggests the pipeline:
"Here's a three-step pipeline for your workflow:

Step 1: Convert picks to meshes
copick convert picks2mesh --config /path/to/config.json \
    --input 'ribosome:user1/manual-001' \
    --output 'ribosome:pipeline/step1-meshes' \
    --method convex_hull

Step 2: Compute convex hull (if not done in step 1)
copick process hull --config /path/to/config.json \
    --input-mesh 'ribosome:pipeline/step1-meshes' \
    --output-mesh 'ribosome:pipeline/step2-hulls'

Step 3: Convert meshes to segmentation
copick convert mesh2seg --config /path/to/config.json \
    --input 'ribosome:pipeline/step2-hulls' \
    --output 'ribosome:pipeline/final-seg@10.0'"

Management Commands

# Check MCP server status (Claude Desktop)
copick setup mcp-status

# Check status for Claude Code
copick setup mcp-status --target code-global
copick setup mcp-status --target code-project

# Remove MCP server configuration (Claude Desktop)
copick setup mcp-remove --server-name "copick-mcp"

# Remove from Claude Code
copick setup mcp-remove --server-name "copick-mcp" --target code-global
copick setup mcp-remove --server-name "copick-mcp" --target code-project

# Force removal without confirmation
copick setup mcp-remove --server-name "copick-mcp" --force

Troubleshooting

1. "MCP server not found": Ensure you've restarted Claude Desktop completely after configuration
2. "Python module not found": Verify the package is installed and the Python path is correct in the config
3. "Permission denied": Check that the Claude config directory is writable
4. "Invalid JSON": Use copick setup mcp-status to validate your configuration
5. "Command not found" during CLI introspection: Ensure copick and all plugin packages (copick-torch, copick-utils) are installed
6. "setup command not found": Make sure copick-mcp is installed (pip install copick-mcp, or the explicit prerelease command above)

Development

# Install in development mode
cd copick-mcp
uv sync --locked --extra test --extra dev

# Format and lint
uv run pre-commit run --all-files

# Run tests
uv run pytest

# Run the server locally for testing
uv run python -m copick_mcp.main

License

MIT License - See LICENSE file for details.

Links

• Copick Documentation
• Model Context Protocol
• FastMCP