PasarGuard MCP

PasarGuard MCP is a local Model Context Protocol server for managing one or more PasarGuard panels through their REST APIs. It is intentionally limited to panel operations. It does not install servers, manage Vultr, SSH into nodes, manage Cloudflare/Fastly, or change provider infrastructure.

The server supports both reading and writing. Writes use a two-step plan/apply workflow: the MCP reads the current object, creates a short-lived confirmation token, and only applies the saved change after the user confirms it. Update plans preserve fields that were not changed, which is important because PasarGuard core and host updates expect complete valid objects.

Install

cd projects/pasarguard-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

Python 3.11 or newer is required.

Configure panels

Static configuration is optional. The MCP can also load a credential file from a chat-driven tool call; see the next section.

Copy config/panels.example.json to a file outside Git, for example ~/.config/pasarguard-mcp/panels.json, and set the password in an environment variable:

export PASARGUARD_MCP_CONFIG="$HOME/.config/pasarguard-mcp/panels.json"
export PASARGUARD_EXAMPLE_PASSWORD='your-panel-password'

The configuration accepts multiple named panels:

{
  "panels": {
    "main": {
      "base_url": "https://panel.example.com",
      "username": "admin",
      "password_env": "PASARGUARD_MAIN_PASSWORD",
      "verify_tls": true,
      "timeout": 30
    },
    "staging": {
      "base_url": "https://staging-panel.example.com",
      "username_env": "PASARGUARD_STAGING_USERNAME",
      "password_env": "PASARGUARD_STAGING_PASSWORD"
    }
  }
}

An existing bearer token can be configured with token_env instead of username/password. Do not commit panel URLs, credentials, tokens, node API keys, certificates, or exported panel objects to this repository.

The local state directory stores confirmation plans and before-snapshots with mode 0700/0600. Override it with PASARGUARD_MCP_STATE_DIR when needed.

MCP client configuration

For a stdio MCP client, use the installed executable:

{
  "mcpServers": {
    "pasarguard": {
      "command": "/absolute/path/to/projects/pasarguard-mcp/.venv/bin/pasarguard-mcp",
      "env": {
        "PASARGUARD_MCP_CONFIG": "/absolute/path/to/panels.json",
        "PASARGUARD_MAIN_PASSWORD": "set-this-in-your-local-client-config"
      }
    }
  }
}

Prefer the client's secret/environment mechanism where it provides one. The MCP server never prints passwords or bearer tokens to stdout.

Chat-based credential files

You can tell Codex where an existing local credential file is instead of putting it in the MCP setup. Ask it to use the load_panel_credentials tool, for example:

Use the PasarGuard credentials in
/Users/me/workspace/memory/30-clients/example/credentials.local.md for the
panel named example. Keep them session-only and test the connection.

The tool reads the file locally and extracts only recognized fields. Supported formats are .env, .md, and .markdown; common keys include PANEL_URL, PASARGUARD_BASE_URL, username, password, and token. The password is never returned by the tool and is kept only in the MCP process by default.

If a Markdown file contains multiple named accounts, select the intended credential block explicitly. For example, a file with a flowship_super_admin block should be loaded with credential_name=flowship_super_admin. The parser strips one matching pair of Markdown backticks or quote characters around values. This matters for entries such as Password: \...`; sending the backticks as part of the password causes PasarGuard to return HTTP 401. When multiple complete credential blocks exist, omitting credential_name` now fails safely instead of merging the username from one account with the password or URL from another.

The tool accepts persist=true only when you explicitly want the profile written to the protected local JSON config. The default is persist=false. Use absolute local paths and keep credential files outside Git repositories.

Tool groups

Read operations:

• list_panels, load_panel_credentials, test_panel
• get_panel_inventory
• list_panel_resource, get_panel_resource
• get_node_realtime_stats, get_panel_system_status

Write planning operations:

• Nodes: create, update, delete, reconnect, sync, reset usage, update core
• Cores: create and update, with explicit optional node restart on updates
• Hosts: create and update
• Groups: create and update
• Users: create and update by numeric ID
• All supported resources can be planned for deletion

Write execution and recovery:

• apply_change applies one still-valid confirmation token.
• inspect_change shows a safe summary without the stored payload.
• plan_rollback creates a new confirmation plan from an applied update's before-snapshot.

The normal sequence is:

1. Inspect the panel or resource.
2. Call the relevant plan_* tool.
3. Show the returned summary and ask the user for confirmation.
4. Call apply_change with the returned token.
5. Verify the resulting resource and node status.

API compatibility

The implementation follows the current public PasarGuard panel API layout, including POST /api/admin/token, /api/nodes, /api/cores, /api/hosts, /api/groups, /api/users, node action endpoints, and ID-based user routes under /api/user/by-id/{user_id}. The panel API can evolve, so endpoint changes should be updated in src/pasarguard_mcp/server.py and covered by tests before release.

Development

.venv/bin/python -m pytest
.venv/bin/python -m compileall -q src tests

Tests use an in-memory HTTP transport and never contact a real panel.

Security boundary

This is an operations tool with write access. Run it locally over stdio, use a least-privileged PasarGuard administrator when possible, keep TLS verification enabled, and review every plan before applying it. Credential-file loading extracts only known fields and does not return passwords. The MCP deliberately does not provide a generic arbitrary-URL request tool.