Copick MCP server
Commit Nov 3, 2026Allows an AI client to explore Copick project data and discover or validate CLI commands for building processing pipelines.
Also known as copick/copick-mcp
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 3, 2026
- License
- MIT
What is Copick MCP?
Copick allows an AI client to explore Copick project data and discover or validate CLI commands for building processing pipelines. It exposes 7 tools, such as main, inference, training.
Summary generated from the project's README
About Copick MCP server
Exploring Copick project data and building processing pipelines is possible through this MCP server. It provides researchers and developers with read-only access to inspect project contents such as runs, picks, segmentations, meshes, and tomograms. By connecting to a local configuration file, an AI client can retrieve detailed metadata, voxel spacings, and object properties to understand the state of a specific project.
Beyond data exploration, the server includes tools for CLI introspection to help users construct complex workflows. It can dynamically list all available Copick commands across groups like inference, training, and conversion, while providing full documentation for each. Users can also validate the syntax of specific command strings using Click's native parsing to ensure accuracy before execution. The server integrates with Claude Desktop or Claude Code through a simple setup process using the Copick CLI.
What you can do with it
- 1Inspect project data contentsAsk the AI to list all available runs or specific picks within a Copick project.
- 2Discover CLI command documentationFind the correct command and required parameters to convert picks into a segmentation.
- 3Validate command syntaxCheck if a complex command string for a processing pipeline is formatted correctly.
- 4Design processing pipelinesRequest a multi-step workflow that converts meshes to segmentations using specific Copick tools.
Written from the project's README. Every use case is checked against a quote from it.
Copick MCP tools 7
Detected from the READMEmaininferencetrainingevaluationprocessconvertlogical
| main | — | |
| inference | — | |
| training | — | |
| evaluation | — | |
| process | — | |
| convert | — | |
| logical | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecopick/copick-mcp is public and reachablegithub.com/copick/copick-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/copick/copick-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCopick MCP Server
A Model Context Protocol (MCP) server for Copick that provides two sets of tools:
- Data Exploration Tools - Browse and query copick project contents (read-only)
- 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 full documentation
- Command validation - Validate copick CLI command syntax using Click's native parsing
- Smart caching - Efficient caching of copick project roots
- Easy setup - Simple CLI for registering with Claude Desktop or Claude Code
Installation
cd copick-mcp
pip install -e .
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:
- Restart Claude Desktop completely
- The Copick MCP tools should now be available
- 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 applicationcode-global- Claude Code global config (~/.claude.json)code-project- Claude Code project-specific config (.mcp.jsonin 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.jsonin your project root
{
"mcpServers": {
"copick-mcp": {
"command": "python",
"args": ["-m", "copick_mcp.main"],
"env": {}
}
}
}
Available Tools
Data Exploration Tools (Read-Only)
All data exploration tools require a config_path parameter pointing to your copick configuration file.
list_runs
List all runs in a Copick project.
- Args:
config_path(str) - Returns: List of run names
get_run_details
Get detailed information about a specific run including voxel spacings, picks, meshes, and segmentations.
- Args:
config_path(str),run_name(str) - Returns: Comprehensive run details
list_objects
List all pickable objects defined in the project.
- Args:
config_path(str) - Returns: List of objects with properties (name, type, label, color, radius, etc.)
list_picks
List picks for a run with optional filtering.
- Args:
config_path(str),run_name(str),object_name(optional),user_id(optional),session_id(optional) - Returns: List of picks with point counts and sample coordinates
list_meshes
List meshes for a run with optional filtering.
- Args:
config_path(str),run_name(str),object_name(optional),user_id(optional),session_id(optional) - Returns: List of meshes
list_segmentations
List segmentations for a run with optional filtering.
- Args:
config_path(str),run_name(str),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:
config_path(str),run_name(str),voxel_spacing(float) - Returns: List of tomograms with feature information
list_voxel_spacings
List all voxel spacings available for a run.
- Args:
config_path(str),run_name(str) - Returns: List of voxel spacings with tomogram counts
get_project_info
Get general project information and statistics.
- Args:
config_path(str) - Returns: Project metadata and entity counts
get_json_config
Get the raw JSON configuration of the project.
- Args:
config_path(str) - Returns: Complete configuration dictionary
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.
- Returns: Complete command tree including:
main: Core commands (add, browse, config, deposit, info, new, stats, sync)inference: Inference commands (e.g., membrain-seg)training: Training commandsevaluation: Evaluation commandsprocess: Processing commands (downsample, fit-spline, hull, skeletonize, etc.)convert: Conversion commands (picks2seg, mesh2seg, seg2picks, etc.)logical: Logical operations (clipmesh, clippicks, meshop, segop, etc.)
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
- Missing required parameters
- Parameter type errors
- Helpful error messages from Click
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
- "MCP server not found": Ensure you've restarted Claude Desktop completely after configuration
- "Python module not found": Verify the package is installed and the Python path is correct in the config
- "Permission denied": Check that the Claude config directory is writable
- "Invalid JSON": Use
copick setup mcp-statusto validate your configuration - "Command not found" during CLI introspection: Ensure copick and all plugin packages (copick-torch, copick-utils) are installed
- "setup command not found": Make sure copick-mcp is installed (
pip install -e .from the copick-mcp directory)
Development
# Install in development mode
cd copick-mcp
pip install -e ".[dev]"
# Format code
black src/
# Lint
ruff check --fix src/
# Run the server locally for testing
python -m copick_mcp.main
License
MIT License - See LICENSE file for details.
Links
Copick MCP questions
What tools does Copick MCP provide?
It exposes 7 tools, including main, inference, training, evaluation, process.
Can I use this server with Claude Code?
Yes, you can register it globally or for a specific project using the --target option.
What kind of data can I explore with the server?
The server provides read-only access to list and inspect runs, picks, segmentations, meshes, tomograms, and project metadata.
Does the server help with building processing pipelines?
Yes, it includes CLI introspection tools to discover commands and validate command syntax.