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

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

# 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:

"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])