# Overlord MCP Server

MCP (Model Context Protocol) server for the Overlord C2 framework — gives AI agents direct access for management, monitoring, debugging, and plugin development.

66+ tools across categories: clients, plugins, builds, users, audit logs, database inspection, server configuration, SOCKS5 proxies, and notifications.

## Quick Start

```bash
pip install -e .
python -m overlord_mcp
```

Auto-discovery finds your Overlord instance automatically:

| Scenario | What happens |
|----------|-------------|
| Docker container running | Extracts URL + credentials from container env |
| Local `.env` or `config.json` | Parses settings automatically |
| `OVERLORD_URL` env var set | Connects directly |
| Nothing found | Prompts for URL once, then saves for all future sessions |

Profiles and credentials are persisted to `~/.overlord-mcp/` (never stored in this repo).

## Manual Setup

```bash
# Via environment variables
OVERLORD_URL=https://localhost:9874 OVERLORD_USERNAME=admin OVERLORD_PASSWORD=yourpass python -m overlord_mcp

# Or from within an MCP client
setup(url='https://localhost:9874', username='admin', password='yourpass', tls_verify=false)
```

## Claude Code Setup

Add to your `C:\Users\<you>\.claude.json` under the `mcpServers` key:

```json
"overlord": {
  "command": "python",
  "args": ["-m", "overlord_mcp"],
  "cwd": "C:/path/to/Overlord-MCP"
}
```

Or use the `/mcp` menu in Claude Code to add it interactively.

On first use, call `setup()` with your Overlord server URL and credentials (or let auto-discovery handle it).

## Capabilities

| Capability | What It Enables | How It's Detected |
|------------|----------------|-------------------|
| `api` | All REST API tools | Always available if URL is known |
| `db_direct` | Read-only SQLite queries (`db_query`, `db_list_tables`, etc.) | Data directory found (Docker volume or local path) |
| `docker_logs` | Server log viewing (`get_server_logs`) | Docker daemon + container found |
| `docker_exec` | Container command execution | Docker daemon + container found |

Tools gracefully report when a capability is unavailable.

## Tool Reference

### Connection & Profiles
`setup` `status` `switch_profile` `list_profiles` `delete_profile`

### Health & Metrics
`health_check` `get_version` `get_metrics` `get_metrics_history`

### Client Management
`list_clients` `get_client` `set_client_nickname` `set_client_tag` `set_client_bookmark` `set_client_group` `create_group` `list_groups` `delete_client` `delete_offline_clients` `ping_client`

### Plugin Management
`list_plugins` `get_plugin` `set_plugin_enabled` `set_plugin_auto_load` `plugin_load_to_client` `plugin_unload_from_client` `plugin_send_event` `plugin_get_events` `plugin_list_data` `plugin_read_data` `plugin_write_data` `plugin_delete_data` `plugin_exec`

### Builds
`list_builds` `get_build` `list_build_profiles` `save_build_profile` `delete_build_profile`

### Database (Read-Only)
`db_list_tables` `db_describe_table` `db_query` `db_get_stats`

### Users
`list_users` `get_user` `get_my_info`

### Configuration (Secrets Masked)
`get_config` `get_security_config` `get_enrollment_config` `get_registration_config` `get_build_rate_limit_config` `get_notifications_config` `update_notifications_config` `update_security_config` `update_enrollment_config`

### Audit & Logs
`get_audit_logs` `get_audit_stats` `list_banned_ips` `get_server_logs`

### Automation
`list_auto_scripts` `get_auto_script` `list_auto_deploys` `get_auto_deploy`

### Files & Proxies
`list_shared_files` `get_shared_file_info` `list_proxies` `get_cert_info`

## Security

- All secrets (JWT keys, tokens, passwords, API keys) masked as `***` in tool outputs
- Direct database access is read-only — `mode=ro`, SELECT-only validation
- Destructive tools (`delete_client`, `delete_offline_clients`, `delete_build_profile`, `delete_profile`, `plugin_delete_data`) annotated with `destructiveHint=true`
- No general-purpose command execution — only `ping_client` exposed
- Plugin binary content never returned — metadata only
- Credentials stored in `~/.overlord-mcp/auth.json` (never committed to repo)

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `OVERLORD_URL` | Overlord server URL |
| `OVERLORD_USERNAME` | Login username |
| `OVERLORD_PASSWORD` | Login password |
| `OVERLORD_TOKEN` | Pre-existing JWT (skip login) |
| `OVERLORD_DATA_DIR` | Data directory path (for direct DB access) |

## Requirements

- Python 3.11+
- Overlord server (local or Docker)
- Optional: `docker-py` for Docker log/exec access (`pip install overlord-mcp-server[docker]`)