# Komodo MCP Server
Model Context Protocol (MCP) server for [Komodo](https://github.com/mbecker20/komodo) - enabling natural language infrastructure management through Claude.
Control your servers, deployments, builds, and infrastructure using conversational AI instead of complex API calls.
## Features
- 60+ MCP tools across 6 modules
- Natural language server management
- Automated deployment workflows
- Real-time monitoring and alerts
- Build pipeline integration
- HMAC-based secure authentication
- Automatic retry logic
- Type-safe TypeScript implementation
## Quick Start
### Installation
```bash
# Clone the repository
git clone https://github.com/your-org/komodo-mcp.git
cd komodo-mcp
# Install dependencies
npm install
# Build the server
npm run build
```
### Configuration
Create a `.env` file with your Komodo credentials:
```bash
KOMODO_URL=https://your-komodo-instance.com
KOMODO_API_KEY=your-api-key
KOMODO_API_SECRET=your-api-secret
```
### Add to Claude
#### Claude Desktop
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"komodo": {
"command": "node",
"args": ["C:/absolute/path/to/komodo-mcp/dist/index.js"],
"env": {
"KOMODO_URL": "https://your-komodo-instance.com",
"KOMODO_API_KEY": "your-api-key",
"KOMODO_API_SECRET": "your-api-secret"
}
}
}
}
```
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Claude Code (CLI)
```bash
claude mcp add komodo -- node /absolute/path/to/komodo-mcp/dist/index.js
```
Then set environment variables in your shell profile.
### First Commands
Ask Claude to interact with your Komodo infrastructure:
```
"Show me all my servers"
"Deploy my API to production"
"What critical alerts do I have?"
"Restart the database server"
"Build version 2.5.0 and deploy to staging"
```
## Available Tools
### Read Module (16 tools)
Read-only access to all Komodo resources:
**Servers**
- `komodo_read_ListServers` - List all servers with filtering
- `komodo_read_GetServer` - Get detailed server information
**Deployments**
- `komodo_read_ListDeployments` - List deployments
- `komodo_read_GetDeployment` - Get deployment details
**Stacks**
- `komodo_read_ListStacks` - List Docker Compose stacks
- `komodo_read_GetStack` - Get stack configuration
**Builds**
- `komodo_read_ListBuilds` - List build configurations
- `komodo_read_GetBuild` - Get build details and history
**Repositories**
- `komodo_read_ListRepos` - List connected repositories
- `komodo_read_GetRepo` - Get repository information
**Procedures**
- `komodo_read_ListProcedures` - List automation procedures
- `komodo_read_GetProcedure` - Get procedure details
**Actions**
- `komodo_read_ListActions` - List configured actions
- `komodo_read_GetAction` - Get action configuration
**Alerts**
- `komodo_read_ListAlerts` - List system alerts
- `komodo_read_GetAlert` - Get detailed alert information
### Execute Module (9 tools)
Trigger actions and manage infrastructure:
**Deployments**
- `komodo_execute_Deploy` - Execute a deployment
**Builds**
- `komodo_execute_Build` - Trigger a build process
**Server Lifecycle**
- `komodo_execute_StartServer` - Start a server
- `komodo_execute_StopServer` - Stop a server
- `komodo_execute_RestartServer` - Restart a server
**Procedures**
- `komodo_execute_RunProcedure` - Execute a procedure
**Actions**
- `komodo_execute_TriggerAction` - Trigger an action
**Repository Operations**
- `komodo_execute_PullRepo` - Pull latest repository changes
- `komodo_execute_CloneRepo` - Clone a repository
## Usage Examples
### Server Management
```
User: Check the health of all production servers
Claude: [Lists all servers with status, CPU, memory metrics]
[Highlights any issues or alerts]
[Suggests actions if needed]
User: Restart the database server
Claude: [Executes restart]
[Monitors status]
[Confirms healthy state]
```
### Deployment Workflow
```
User: Deploy version 2.5.0 to staging then production
Claude: [Triggers build for v2.5.0]
[Deploys to staging]
[Runs health checks]
[Waits for approval]
[Deploys to production]
[Verifies all instances]
```
### Monitoring
```
User: Give me a complete infrastructure health report
Claude: [Analyzes all servers]
[Checks all deployments]
[Reviews active alerts]
[Generates comprehensive report]
[Recommends actions]
```
See [EXAMPLES.md](./docs/EXAMPLES.md) for more real-world scenarios.
## Documentation
### User Guides
- [Usage Guide](./docs/USAGE.md) - Complete usage guide with examples
- [API Reference](./docs/API_REFERENCE.md) - Detailed API documentation for all 60 tools
- [Examples](./docs/EXAMPLES.md) - Real-world usage scenarios
- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Migration Guide](./docs/MIGRATION.md) - Migrate from direct API usage
### Technical Documentation
- [Architecture](./docs/ARCHITECTURE.md) - System architecture and design
- [API Mapping](./docs/API_MAPPING.md) - Komodo API to MCP tool mapping
- [Environment](./docs/ENVIRONMENT.md) - Environment variable configuration
## Development
### Requirements
- Node.js 20+
- TypeScript 5+
- npm 9+
### Build
```bash
npm run build # Build for production
npm run dev # Build and watch for changes
npm run clean # Clean build artifacts
```
### Testing
```bash
npm test # Run all tests
npm run test:watch # Run tests in watch mode
npm run test:coverage # Generate coverage report
```
### Linting & Formatting
```bash
npm run lint # Check code style
npm run lint:fix # Fix code style issues
npm run format # Format code with Prettier
npm run format:check # Check code formatting
npm run typecheck # TypeScript type checking
```
## Environment Variables
### Required
| Variable | Description | Example |
|----------|-------------|---------|
| `KOMODO_URL` | Komodo API base URL | `https://komodo.example.com` |
| `KOMODO_API_KEY` | API key for authentication | `km_key_abc123...` |
| `KOMODO_API_SECRET` | API secret for HMAC signing | `km_secret_xyz789...` |
### Optional
| Variable | Description | Default |
|----------|-------------|---------|
| `KOMODO_TIMEOUT` | Request timeout (ms) | `30000` |
| `KOMODO_RETRY_COUNT` | Number of retries on failure | `3` |
| `KOMODO_RETRY_DELAY` | Delay between retries (ms) | `1000` |
| `KOMODO_LOG_LEVEL` | Logging level | `info` |
| `KOMODO_SSL_VERIFY` | Verify SSL certificates | `true` |
See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for complete configuration details.
## License
MIT License - see [LICENSE](./LICENSE) file for details.
## Support
- **Documentation**: [docs/](./docs/)
- **Issues**: [GitHub Issues](https://github.com/your-org/komodo-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/komodo-mcp/discussions)
- **Komodo**: [github.com/mbecker20/komodo](https://github.com/mbecker20/komodo)
## Acknowledgments
- [Komodo](https://github.com/mbecker20/komodo) - Infrastructure automation platform
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
- [Anthropic](https://www.anthropic.com) - Claude AI assistant
---
**Built with ❤️ for the Komodo community**
Start managing your infrastructure naturally - no more complex API calls, just conversation with Claude.
Get started: [Quick Start](#quick-start) | [Documentation](./docs/USAGE.md) | [Examples](./docs/EXAMPLES.md)
