@crusoeai/cloud-mcp: Crusoe Cloud MCP Server

A TypeScript MCP (Model Context Protocol) server that enables AI assistants to query Crusoe Cloud infrastructure through natural language. All tools are read-only for safety when used with AI agents.

Installation

Add the MCP server to Claude Code:

claude mcp add crusoe-cloud -- npx @crusoeai/cloud-mcp

To make the server available globally (in any directory), add -s user:

claude mcp add crusoe-cloud -s user -- npx @crusoeai/cloud-mcp

Prerequisites: Crusoe Cloud credentials configured in ~/.crusoe/config (same format as the Crusoe CLI).

Using Environment Variables

To use a specific profile or override the default project, pass environment variables using the --env (-e) flag:

# Use a specific profile from ~/.crusoe/config
claude mcp add crusoe-cloud -e CRUSOE_PROFILE=profile1 -- npx @crusoeai/cloud-mcp

# Override the default project (by ID, not name)
claude mcp add crusoe-cloud -e CRUSOE_PROJECT=abc123-def456 -- npx @crusoeai/cloud-mcp

# Combine both
claude mcp add crusoe-cloud -e CRUSOE_PROFILE=profile1 -e CRUSOE_PROJECT=abc123-def456 -- npx @crusoeai/cloud-mcp

Add -s user to any of these commands to install globally.

Alternatively, edit ~/.claude/settings.json directly:

{
	"mcpServers": {
		"crusoe-cloud": {
			"command": "npx",
			"args": ["@crusoeai/cloud-mcp"],
			"env": {
				"CRUSOE_PROFILE": "profile1",
				"CRUSOE_PROJECT": "abc123-def456"
			}
		}
	}
}

Quick Start

1. Ensure you have Crusoe CLI credentials configured:

   # If you haven't already, install and configure the Crusoe CLI
   crusoe config init

2. Verify your configuration:

   cat ~/.crusoe/config
   # Should show [default] section with access_key_id and secret_key

3. Add to Claude Code:

   claude mcp add crusoe-cloud -- npx @crusoeai/cloud-mcp

4. Test with Claude: "List my Crusoe Cloud projects"

Available Tools

Discovery

• get_organization - Get organization details
• list_locations - List available zones/locations
• list_vm_types - List VM types with availability
• list_kubernetes_versions - List supported Kubernetes versions
• get_resource_relationships - Discover all Crusoe Cloud resources and their relationships

Project & Identity

• get_current_project - Get the active project
• use_project - Switch to a different project
• list_available_projects - List all accessible projects
• get_user_identity - Get current user details

Compute

• list_vms, get_vm - Virtual machines
• list_instance_templates, get_instance_template - Instance templates
• list_instance_groups, get_instance_group, list_group_instances - Instance groups

Images

• list_images, get_image - Public VM images
• list_custom_images, get_custom_image - Custom VM images

Storage

• list_disks, get_disk - Persistent disks
• list_disk_snapshots, get_disk_snapshot - Disk snapshots

Networking

• list_vpc_networks, get_vpc_network - VPC networks
• list_vpc_subnets, get_vpc_subnet - VPC subnets
• list_firewall_rules, get_firewall_rule - Firewall rules
• list_load_balancers, get_load_balancer - External load balancers

Kubernetes

• list_kubernetes_clusters, get_kubernetes_cluster - Kubernetes clusters
• list_kubernetes_node_pools, get_kubernetes_node_pool, list_kubernetes_node_pool_instances - Node pools

Billing & Quotas

• list_org_quotas - Organization-level quotas
• list_project_quotas - Project-level quotas
• get_usage_by_project - Usage data for billing
• get_gpu_tracking - GPU utilization and reservation tracking

Audit

• list_audit_logs - Organization audit logs for compliance and security

Configuration

| Variable | Description | Default | | ---------------- | ----------------------------------------------------- | ------------------------------------------------ | | CRUSOE_PROFILE | Profile section to use from ~/.crusoe/config | profile key in config, or "default" if unset | | CRUSOE_PROJECT | Override the default project by ID (takes precedence) | Resolved from default_project name in config |

Troubleshooting

"Failed to read Crusoe config"

• Verify config exists: ls -la ~/.crusoe/config
• Check it's valid TOML format
• Ensure file is readable by current user

"No project ID provided"

• Set default_project in ~/.crusoe/config (this is the project name, which gets resolved to an ID on startup)
• Or set the CRUSOE_PROJECT environment variable (this is the project ID directly, which takes precedence over default_project)

Rate limit errors

• The server limits to 60 requests/minute
• Wait 60 seconds and retry
• This protects against LLM retry loops

Development

See DEVELOPMENT.md for internal documentation on building, testing, and contributing.

This is an experimental tool. Use with caution and at your own risk.

This MCP server enables AI assistants to query your Crusoe Cloud infrastructure through natural language. While the server performs read-only operations, you should be aware of the following:

Data Privacy

• API responses containing your infrastructure data will be sent to your chosen AI assistant (e.g., Claude, ChatGPT, or other services)
• Your Crusoe API credentials remain local on your machine and are never sent to Crusoe or third-party AI services
• Be mindful that VM names, network configurations, and other infrastructure details may contain sensitive business information

AI Decision-Making

• Always verify information before taking action. AI assistants may misinterpret infrastructure data or provide incorrect recommendations
• This tool provides information only — it cannot and does not take any destructive actions
• Never rely solely on AI-generated advice for critical infrastructure decisions

No Warranty

This software is provided "AS IS" without warranty of any kind. Crusoe makes no guarantees regarding:

• Stability or reliability of the tool
• Accuracy of data filtering or response formatting
• Compatibility with all AI assistants or future API changes