Initial commit: Incus MCP Server implementation
- Complete MCP server for Incus container management - 10 tools for instance lifecycle operations (create, start, stop, etc.) - 2 resources for instance and remote server data - Support for multiple Incus remotes with TLS authentication - TypeScript implementation with comprehensive error handling - Test suite for validation and integration testing - MCP configuration for Claude Code integration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
kappa
315
README.md
Normal file
315
README.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 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 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`):
|
||||
|
||||
```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": "jp1"}
|
||||
# Lists instances only from the jp1 remote server
|
||||
|
||||
incus_show_instance: {"name": "myapp", "remote": "kr1"}
|
||||
# Shows details for 'myapp' instance on kr1 server
|
||||
```
|
||||
|
||||
### Command Execution
|
||||
```bash
|
||||
incus_exec_command: {
|
||||
"instance": "webserver",
|
||||
"command": "apt update && apt install -y nginx",
|
||||
"remote": "jp1"
|
||||
}
|
||||
```
|
||||
|
||||
### 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/).
|
||||
Reference in New Issue
Block a user