nebius/contree-mcp

nebius/contree-mcp

Description: Run code in isolated cloud containers. ConTree gives AI agents secure sandboxed execution environments with full root access, network, and persistent images.

Language: Python

License: Apache-2.0

Stars: 1

Forks: 1

Open issues: 6

Created: 2026-01-29T11:56:22Z

Pushed: 2026-05-18T17:09:03Z

Default branch: master

Fork: no

Archived: no

README:

ConTree MCP Server


Run code in isolated cloud containers. ConTree gives AI agents secure sandboxed execution environments with full root access, network, and persistent images.

Why ConTree?

Fearless experimentation. Agents can:

• Run destructive commands (rm -rf /, dd, kernel exploits) - nothing escapes the sandbox
• Make mistakes freely - revert to any previous image UUID at zero cost
• Execute potentially dangerous user requests - ConTree IS the safe runtime for risky operations
• Break things on purpose - corrupt filesystems, crash kernels, test failure modes

Every container is isolated. Every image is immutable. Branching is cheap. Mistakes are free.

Quick Setup

1. Get an API Token

Contree is in Early Access. To get an API token, fill out the request form at contree.dev.

2. Create Config File

contree-mcp reads the same auth.ini that `contree-cli` writes, so a single login covers all contree-related tools.

Recommended: install contree-cli (see installation guide) and manage credentials with it rather than editing the file by hand:

contree auth --help # add, switch, list, remove profiles

Default location: $XDG_CONFIG_HOME/contree/auth.ini (typically ~/.config/contree/auth.ini). Override the directory with CONTREE_HOME.

If you really need to write it by hand:

[DEFAULT]
profile = default

[profile:default]
type = iam
url = https://api.tokenfactory.nebius.com/sandboxes
token =
project =

For the legacy JWT flow (contree.dev), use:

[profile:default]
type = jwt
url = https://contree.dev
token =

3. Configure Your MCP Client

Claude Code

claude mcp add --transport stdio contree -- $(which uvx) contree-mcp

Restart Claude Code or run /mcp to verify.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.contree]
command = "uvx"
args = ["contree-mcp"]

Claude Desktop

Add to config file:

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

{"mcpServers": {"contree": {"command": "uvx", "args": ["contree-mcp"]}}}

> Note: You can alternatively pass credentials via environment variables (CONTREE_TOKEN, CONTREE_URL, CONTREE_PROJECT, CONTREE_PROFILE) in your MCP client config, but this is not recommended as tokens may appear in process listings.

Manual Installation

# Using uv
uv pip install contree-mcp

# Using pip
pip install contree-mcp

# Run manually (IAM auth)
contree-mcp --token YOUR_TOKEN --project YOUR_PROJECT

# Or pick a profile from ~/.config/contree/auth.ini
contree-mcp --profile staging

# HTTP mode (for network access)
contree-mcp --mode http --http-port 9452 --profile default

# Visit http://localhost:9452/ for interactive documentation with
# setup guides, tool reference, and best practices.

Container Installation (Alpine/Ubuntu/Debian)

These distros enable PEP 668, which protects the system Python from pip install mutations. Use an isolated tool installer:

# Recommended: isolated install, no PEP 668 conflicts
uv tool install contree-mcp
# or
pipx install contree-mcp

Both put contree-mcp on your PATH while keeping its dependencies in a private venv. uvx contree-mcp (used by the MCP-client snippets above) also works without installation since it spawns an ephemeral env per invocation.

If you really must install into the system Python

pip install --break-system-packages contree-mcp

--break-system-packages overrides PEP 668 protections and can put your system Python in an inconsistent state. Prefer uv tool install / pipx unless you have a specific reason.

Configuration

| Argument | Environment Variable | Default | |----------|---------------------|---------| | - | CONTREE_HOME | $XDG_CONFIG_HOME/contree (~/.config/contree) | | --profile | CONTREE_PROFILE | active profile from config | | --token | CONTREE_TOKEN | from config | | --url | CONTREE_URL | from config (IAM default: https://api.tokenfactory.nebius.com/sandboxes) | | --project | CONTREE_PROJECT | from config (required for IAM auth) | | --mode | - | stdio | | --http-port | - | 9452 | | --log-level | - | warning |

Resolution priority for credentials: CLI flag > environment variable > profile in `config.ini`.

Available Tools

Command Execution

| Tool | Description | |------|-------------| | contree_run | Execute command in container (spawns microVM). Supports wait=false for async execution. |

Image Management

| Tool | Description | |------|-------------| | contree_list_images | List available container images | | contree_get_image | Get image details by UUID or tag | | contree_import_image | Import OCI image from registry (requires authentication) | | contree_registry_token_obtain | Open browser to create PAT for registry authentication | | contree_registry_auth | Validate and store registry credentials | | contree_set_tag | Set or remove a tag for an image |

File Transfer

| Tool | Description | |------|-------------| | contree_upload | Upload a file to ConTree for use in containers | | contree_download | Download a file from a container image to local filesystem | | contree_rsync | Sync local files to ConTree with caching and deduplication |

Image Inspection

| Tool | Description | |------|-------------| | contree_list_files | List files and directories in an image (no VM needed) | | contree_read_file | Read a file from an image (no VM needed) |

Operations

| Tool | Description | |------|-------------| | contree_list_operations | List operations (running or completed) | |…