incus-mcp/README.md

Incus MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Incus containers and virtual machines. This server provides a complete set of tools and resources to interact with Incus instances locally and across remote servers through the MCP protocol.

⭐ Key Features

🛠 Tools (10 Available)

• incus_list_instances: List all instances with their current status (supports remote servers)
• incus_show_instance: Show detailed information about a specific instance
• incus_start_instance: Start stopped instances
• incus_stop_instance: Stop running instances (with optional force flag)
• incus_restart_instance: Restart instances (with optional force flag)
• incus_create_instance: Create new instances from images with custom configuration
• incus_delete_instance: Delete instances (with optional force flag)
• incus_exec_command: Execute commands inside running instances
• incus_list_remotes: List all configured remote servers
• incus_info: Show comprehensive Incus system information

📚 Resources (2 Available)

• incus://instances/list: JSON list of all instances across all remotes
• incus://remotes/list: JSON list of all configured remote servers with connection details

🌐 Multi-Remote Support

Seamlessly works with all your configured Incus remotes:

• Local instances: Direct access to local Incus daemon
• Remote servers: Full support for TLS-authenticated remote Incus servers
• Image sources: Integration with LinuxContainers.org, Docker Hub, GitHub Container Registry
• Automatic discovery: Automatically detects and works with existing remote configurations

📋 Prerequisites

• Node.js 18+: Required for running the TypeScript/JavaScript server
• Incus installed: Working Incus installation with daemon running
• Proper permissions: User must be in incus group or have appropriate file access
• Remote configuration: Pre-configured remote servers (optional but recommended)

🚀 Quick Start

Installation from NPM (Recommended)

# Global installation (recommended for Claude Desktop)
npm install -g @ironclads/incus-mcp

# Verify installation
incus-mcp --version
which incus-mcp

Installation from Source

# Clone the repository
git clone https://github.com/your-username/incus-mcp.git
cd incus-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Test the installation
npm test

Verify Incus Setup

# Check Incus is working
incus version
incus list
incus remote list

💻 Usage

Standalone MCP Server

# Run the server directly
node build/index.js

# Development mode with auto-reload
npm run dev

# Production mode
npm start

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration (~/.config/claude-desktop/config.json):

Option 1: Using Global NPM Installation (Recommended)

{
  "mcpServers": {
    "incus": {
      "command": "incus-mcp",
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Option 2: Using Local Installation

{
  "mcpServers": {
    "incus": {
      "command": "node",
      "args": ["/absolute/path/to/incus-mcp/build/index.js"],
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Integration with Claude Code

The repository includes .mcp.json for local development:

{
  "mcpServers": {
    "incus": {
      "command": "node",
      "args": ["/Users/kaffa/mcp-servers/incus-mcp/build/index.js"]
    }
  }
}

🔧 Development

Development Workflow

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run comprehensive tests
node test/simple-test.js
node test/resource-test.js

# Code quality
npm run lint
npm run format

Project Structure

incus-mcp/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   ├── incus.ts          # Incus command execution utilities  
│   └── schemas.ts        # MCP tool/resource schema definitions
├── test/
│   ├── simple-test.js    # Basic functionality tests
│   └── resource-test.js  # Resource reading tests
├── build/                # Compiled JavaScript output
├── .mcp.json            # Local MCP server configuration
└── mcp-config-example.json  # Claude Desktop config template

⚙️ Configuration

System Requirements

The server automatically uses your existing Incus configuration:

1. Incus daemon running: systemctl status incus (Linux) or check process list
2. User permissions: Member of incus group or appropriate file access
3. Remote servers: Pre-configured remotes work automatically

Setting up Remote Servers

# Add a remote Incus server
incus remote add myserver https://server.example.com:8443

# Add with custom certificate
incus remote add myserver https://server.example.com:8443 --password

# List all configured remotes
incus remote list

# Test remote connection
incus list myserver:

Environment Variables

# Optional: Custom PATH for incus binary
export PATH="/opt/incus/bin:$PATH"

# Optional: Debug MCP communication
export MCP_DEBUG=1

📖 Usage Examples

Basic Instance Management

# Via MCP tools (conceptual - actual usage through MCP client)
incus_list_instances: {}
# Returns: List of all instances across all remotes

incus_create_instance: {
  "name": "webserver", 
  "image": "ubuntu:22.04",
  "config": {"limits.cpu": "2", "limits.memory": "2GB"}
}

incus_start_instance: {"name": "webserver"}

Remote Operations

incus_list_instances: {"remote": "remote1"}
# Lists instances only from the remote1 server

incus_show_instance: {"name": "myapp", "remote": "remote2"}  
# Shows details for 'myapp' instance on remote2 server

Command Execution

incus_exec_command: {
  "instance": "webserver",
  "command": "apt update && apt install -y nginx",
  "remote": "remote1"
}

Resource Access

• incus://instances/list → JSON array of all instances with full metadata
• incus://remotes/list → JSON object with remote server configurations

🛡️ Security & Error Handling

Security Features

• Input validation: All arguments validated with Zod schemas
• Command sanitization: No shell injection vulnerabilities
• Permission isolation: Uses existing Incus user permissions
• Remote auth: Leverages configured TLS certificates
• Audit trail: All commands logged through Incus

Error Handling

• Graceful failures: Comprehensive error messages without exposing internals
• Network timeouts: Proper handling of remote server connectivity issues
• Permission errors: Clear guidance for permission-related problems
• Invalid arguments: Detailed validation error messages

🐛 Troubleshooting

Common Issues & Solutions

1. Permission Denied

# Add user to incus group
sudo usermod -a -G incus $USER
newgrp incus

# Verify permissions
id | grep incus
incus list  # Should work without sudo

2. Incus Not Found

# Check installation
which incus
incus version

# Install on Ubuntu/Debian
curl -fsSL https://packagecloud.io/install/repositories/candid/incus/script.deb.sh | sudo bash
sudo apt install incus

# Install on macOS
brew install incus

3. Remote Connection Issues

# Verify remote configuration
incus remote list

# Test connectivity
incus info remote-name:

# Re-add problematic remote
incus remote remove old-remote
incus remote add old-remote https://server:8443

4. MCP Server Issues

# Test MCP server directly
node build/index.js
# Should show: "Incus MCP server running on stdio"

# Check build output
npm run build
ls -la build/

# Run test suite
node test/simple-test.js

Debug Mode

# Enable verbose logging
DEBUG=mcp* node build/index.js

# Test individual tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: node test/*.js
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

---

Built with ❤️ for the Incus and MCP communities

For support, please open an issue on GitHub or check the MCP documentation.