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)
```bash
# Global installation (recommended for Claude Desktop)
npm install -g @ironclads/incus-mcp

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

### Installation from Source
```bash
# 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
```bash
# Check Incus is working
incus version
incus list
incus remote list
```

## 💻 Usage

### Standalone MCP Server
```bash
# 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)
```json
{
  "mcpServers": {
    "incus": {
      "command": "incus-mcp",
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}
```

#### Option 2: Using Local Installation
```json
{
  "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:

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

## 🔧 Development

### Development Workflow
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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](https://modelcontextprotocol.io/).