PatchMon MCP Server

An MCP (Model Context Protocol) server that connects to a PatchMon instance via its Integration API, so an LLM client (Claude Desktop, Claude Code, etc.) can query host inventory, patch status, and system details, and optionally delete hosts.

Built against PatchMon's documented Integration API: https://docs.patchmon.net/books/patchmon-application-documentation/page/integration-api-documentation

Uses the standalone fastmcp library (v2.x) to implement the MCP server. This is a separate project from, but protocol-compatible with, Anthropic's official mcp Python SDK — any MCP client (Claude Desktop, Claude Code, MCP Inspector) works with it identically.

Tools exposed

Tool	Scope needed	Description
list_hosts	host:get	List all hosts, optionally filtered by host group, optionally with inline stats
get_host_stats	host:get	Package/repo statistics for one host
get_host_info	host:get	OS, agent version, host groups for one host
get_host_network	host:get	IP, gateway, DNS, interfaces
get_host_system	host:get	CPU/RAM/disk/kernel/uptime/reboot status
get_host_packages	host:get	Installed packages, optionally updates-only
get_host_package_reports	host:get	Agent check-in report history
get_host_agent_queue	host:get	Agent job queue + job history
get_host_notes	host:get	Free-text notes on a host
get_host_integrations	host:get	Integration status (e.g. Docker)
delete_host	host:delete	Permanently delete a host (guarded by confirm=true)
get_host_overview	host:get	Combined info + stats + system in one call
find_hosts_needing_security_updates	host:get	Hosts with pending security updates

1. Create a PatchMon API credential

1. Log in to your PatchMon instance as an administrator.
2. Go to Settings → Integrations → Auto-Enrollment & API.
3. Click New Token, choose usage type API.
4. Grant scope host: get (add delete too if you want the delete_host tool to work).
5. Copy the Token Key (patchmon_ae_...) and Token Secret — the secret is shown only once.

2. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure

The server reads its configuration from environment variables:

Variable	Required	Default	Description
PATCHMON_URL	yes	—	Base URL of your PatchMon instance, e.g. https://patchmon.example.com
PATCHMON_API_KEY	yes	—	Token key (patchmon_ae_...)
PATCHMON_API_SECRET	yes	—	Token secret
PATCHMON_API_VERSION	no	v1	API version path segment
PATCHMON_VERIFY_SSL	no	true	Set to false to skip TLS verification (dev/self-signed only)
PATCHMON_TIMEOUT	no	30	Request timeout in seconds

4. Run standalone (for testing)

export PATCHMON_URL="https://patchmon.example.com"
export PATCHMON_API_KEY="patchmon_ae_abc123"
export PATCHMON_API_SECRET="your_secret_here"
python server.py

The server speaks MCP over stdio, so it's normally launched by an MCP client rather than run interactively.

Note: list_tools.py (a small helper for querying the server's tool list from the command line) uses the official mcp package's client classes (ClientSession, stdio_client). That's independent of which SDK the server is built on — any MCP client can talk to any MCP server. If you don't already have mcp installed for the client side, add it with pip install mcp.

5. Connect it to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "patchmon": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "PATCHMON_URL": "https://patchmon.example.com",
        "PATCHMON_API_KEY": "patchmon_ae_abc123",
        "PATCHMON_API_SECRET": "your_secret_here"
      }
    }
  }
}

Restart Claude Desktop and the patchmon tools will be available.

6. Connect it to Claude Code

claude mcp add patchmon \
  --env PATCHMON_URL=https://patchmon.example.com \
  --env PATCHMON_API_KEY=patchmon_ae_abc123 \
  --env PATCHMON_API_SECRET=your_secret_here \
  -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Notes on safety

• delete_host is destructive and irreversible. It requires an explicit confirm=true argument in addition to the host:delete scope, as a guard against accidental invocation.
• Credentials are read from environment variables only — never hard-code them into the server or commit them to version control.
• Consider restricting the PatchMon API credential to specific IPs and setting an expiration date (see PatchMon's Security Best Practices).