termix-mcp

# termix-mcp

[![CI](https://github.com/sujirodev/termix-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sujirodev/termix-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/termix-mcp?cacheSeconds=3600)](https://pypi.org/project/termix-mcp/)
[![License](https://img.shields.io/github/license/sujirodev/termix-mcp)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/termix-mcp?cacheSeconds=3600)](https://pypi.org/project/termix-mcp/)
[![Docker](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fsujirodev%2Ftermix-mcp%2Fbadges%2Fdocker.json)](https://github.com/sujirodev/termix-mcp/pkgs/container/termix-mcp)

[MCP](https://modelcontextprotocol.io) server for [Termix](https://github.com/LukeGus/Termix), the self-hosted SSH/RDP/VNC manager. Lets an agent (Claude Desktop, Claude Code, Cursor, VS Code...) list and operate your Termix's hosts, snippets, dashboard, metrics and audit trail, built on top of [termix-sdk](https://github.com/sujirodev/termix-sdk).

Not a 1:1 wrapper of the Termix API: it's a curated set of tools, secure by default (no secrets, no persistent SSH session, no destructive tools outside of explicit toolsets).

<!-- mcp-name: io.github.sujirodev/termix-mcp -->

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sujirodev%2Ftermix--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sujirodev/termix-mcp)

## Install

```bash
uvx termix-mcp
```

Alternatives: `pip install termix-mcp` or the `ghcr.io/sujirodev/termix-mcp` image.

Requires a Termix API key (`tmx_...`) with the minimum RBAC permissions for what the agent will do - see [SECURITY.md](SECURITY.md).

## Configure in your client

Claude Desktop / Claude Code (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "termix": {
      "command": "uvx",
      "args": ["termix-mcp"],
      "env": {
        "TERMIX_URL": "https://termix.example.com",
        "TERMIX_API_KEY": "tmx_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Cursor / VS Code: same format, in each one's MCP configuration file.

## Install via the MCP Registry

termix-mcp is published in the official [MCP Registry](https://registry.modelcontextprotocol.io) under the name `io.github.sujirodev/termix-mcp`, with both a PyPI (`uvx`) package and an OCI (Docker) image listed - see [server.json](server.json).

Clients that support registry-based discovery can find and install it directly from there instead of hand-writing the JSON config above:

```bash
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sujirodev/termix-mcp"
```

Then follow your client's own "add from registry" flow, searching for `io.github.sujirodev/termix-mcp`. You'll still need to set `TERMIX_URL` and `TERMIX_API_KEY` yourself - the registry entry doesn't carry your credentials.

## You say / what happens

| You say | What the tool does |
|---|---|
| "what hosts do I have registered?" | `termix_list_hosts` |
| "show me the metrics for host X" | `termix_get_host_metrics` |
| "run snippet Y on host X" | `termix_run_snippet` (blocked in read-only mode) |
| "create a new host for this server" | `termix_create_host` (blocked in read-only mode) |
| "what audit activity happened this week?" | `termix_list_audit_events` |

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `TERMIX_URL` | required | Termix base URL |
| `TERMIX_API_KEY` | required | `tmx_...` API key (JWT/TOTP are not supported) |
| `TERMIX_SERVICE_URLS` | empty | JSON `{"database": "http://..."}` for installs without a proxy |
| `TERMIX_VERIFY_SSL` | `true` | Validates the TLS certificate |
| `TERMIX_TIMEOUT` | `30` | Timeout per request (s) |
| `TERMIX_MAX_RETRIES` | `2` | Passed through to the SDK |
| `TERMIX_MCP_READ_ONLY` | `false` | Hides and blocks write tools |
| `TERMIX_MCP_TOOLSETS` | `default` | `default`, `all`, or a list `hosts,snippets,files` |
| `TERMIX_MCP_ENABLED_TOOLS` | empty | Allowlist by tool name |
| `TERMIX_MCP_DISABLED_TOOLS` | empty | Denylist by tool name |
| `TERMIX_MCP_REDACT_SECRETS` | `true` | Masks secrets in all outputs |
| `TERMIX_MCP_MAX_ITEMS` | `50` | Default item limit for listings |
| `TERMIX_MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
| `TERMIX_MCP_HTTP_HOST` / `_PORT` | `127.0.0.1` / `8765` | HTTP transport bind |
| `TERMIX_MCP_HTTP_PATH` | generated and logged | Secret path of the HTTP endpoint |
| `TERMIX_MCP_LOG_LEVEL` | `INFO` | Log level (stderr on stdio, stdout on http) |

## Toolsets

Enabled by default: `hosts`, `snippets`, `dashboard`, `metrics`, `system`, `audit`.

Opt-in (`TERMIX_MCP_TOOLSETS=hosts,files,docker,...`): `credentials`, `files`, `docker`, `tunnels`, `alerts`, `automations`, `users`.

Disabled and explicit (never included in `all`): `admin`, `dangerous`.

`TERMIX_MCP_READ_ONLY=true` hides and blocks every tool that isn't read-only, in any toolset.

## Tools

<details>
<summary>Full tool list (generated by <code>scripts/generate_tool_docs.py</code>)</summary>

<!-- TOOLS_TABLE_START -->
| Tool | Toolset | Read-only | Destructive | Flags |
|---|---|:---:|:---:|---|
| `termix_get_audit_forwarding` | admin | yes | no | admin |
| `termix_get_branding` | admin | yes | no | admin |
| `termix_get_encryption_status` | admin | yes | no | admin |
| `termix_get_host_defaults` | admin | yes | no | admin |
| `termix_get_termix_id_status` | admin | yes | no | admin |
| `termix_list_sso_providers` | admin | yes | no | admin |
| `termix_update_branding` | admin | no | no | admin |
| `termix_acknowledge_alert_firing` | alerts | no | no | - |
| `termix_create_alert_rule` | alerts | no | no | - |
| `termix_delete_alert_rule` | alerts | no | yes | - |
| `termix_list_alert_rules` | alerts | yes | no | - |
| `termix_get_session_log` | audit | yes | no | - |
| `termix_list_audit_events` | audit | yes | no | - |
| `termix_list_session_logs` | audit | yes | no | - |
| `termix_get_automation` | automations | yes | no | - |
| `termix_list_automations` | automations | yes | no | - |
| `termix_list_fleets` | automations | yes | no | - |
| `termix_run_automation` | automations | no | no | data-access |
| `termix_create_credential` | credentials | no | no | - |
| `termix_delete_credential` | credentials | no | yes | - |
| `termix_get_credential` | credentials | yes | no | - |
| `termix_list_credentials` | credentials | yes | no | - |
| `termix_reveal_credential` | credentials | yes | no | data-access |
| `termix_update_credential` | credentials | no | no | - |
| `termix_get_dashboard_summary` | dashboard | yes | no | - |
| `termix_get_homepage` | dashboard | yes | no | - |
| `termix_list_open_tabs` | dashboard | yes | no | - |
| `termix_list_workspaces` | dashboard | yes | no | - |
| `termix_get_container` | docker | yes | no | data-access |
| `termix_get_container_logs` | docker | yes | no | data-access |
| `termix_get_container_stats` | docker | yes | no | data-access |
| `termix_list_containers` | docker | yes | no | data-access |
| `termix_restart_container` | docker | no | no | data-access |
| `termix_start_container` | docker | no | no | data-access |
| `termix_stop_container` | docker | no | no | data-access |
| `termix_create_folder` | files | no | no | data-access |
| `termix_delete_file` | files | no | yes | data-access |
| `termix_list_files` | files | yes | no | data-access |
| `termix_move_file` | files | no | no | data-access |
| `termix_read_file` | files | yes | no | data-access |
| `termix_rename_file` | files | no | no | data-access |
| `termix_write_file` | files | no | no | data-access |
| `termix_create_host` | hosts | no | no | - |
| `termix_delete_host` | hosts | no | yes | - |
| `termix_disable_host_autostart` | hosts | no | no | - |
| `termix_enable_host_autostart` | hosts | no | no | - |
| `termix_get_host` | hosts | yes | no | - |
| `termix_get_network_topology` | hosts | yes | no | - |
| `termix_list_host_folders` | hosts | yes | no | - |
| `termix_list_host_tags` | hosts | yes | no | - |
| `termix_list_hosts` | hosts | yes | no | - |
| `termix_update_host` | hosts | no | no | - |
| `termix_get_host_metrics` | metrics | yes | no | - |
| `termix_get_host_status` | metrics | yes | no | - |
| `termix_get_metrics_history` | metrics | yes | no | - |
| `termix_get_proxmox_stats` | metrics | yes | no | - |
| `termix_list_active_alerts` | metrics | yes | no | - |
| `termix_list_host_statuses` | metrics | yes | no | - |
| `termix_create_snippet` | snippets | no | no | - |
| `termix_delete_snippet` | snippets | no | yes | - |
| `termix_get_snippet` | snippets | yes | no | - |
| `termix_list_snippets` | snippets | yes | no | - |
| `termix_run_snippet` | snippets | no | no | - |
| `termix_update_snippet` | snippets | no | no | - |
| `termix_get_preferences` | system | yes | no | - |
| `termix_get_system_info` | system | yes | no | - |
| `termix_list_api_keys` | system | yes | no | - |
| `termix_create_tunnel` | tunnels | no | no | data-access |
| `termix_delete_tunnel` | tunnels | no | no | data-access |
| `termix_get_tunnel` | tunnels | yes | no | - |
| `termix_list_tunnel_presets` | tunnels | yes | no | - |
| `termix_list_tunnels` | tunnels | yes | no | - |
| `termix_assign_role` | users | no | no | admin |
| `termix_get_user` | users | yes | no | admin |
| `termix_list_credential_access` | users | yes | no | admin |
| `termix_list_folder_access` | users | yes | no | admin |
| `termix_list_roles` | users | yes | no | admin |
| `termix_list_users` | users | yes | no | admin |

Total: 78 tools.
<!-- TOOLS_TABLE_END -->

</details>

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md) for the threat model.

## License

[MIT](LICENSE)