nexterm-mcp

nexterm-mcp

A typed Model Context Protocol server for broad management of Nexterm through its supported REST API.

This community project is not affiliated with or endorsed by the Nexterm project.

Design

nexterm-mcp maps Nexterm resources and actions to explicit MCP tools instead of exposing a generic HTTP request primitive. This keeps tool inputs discoverable, validates common fields before a request is sent, provides MCP read/destructive annotations, and keeps the Nexterm API key outside model-visible arguments.

Version 0.2.0 provides 89 MCP tools and is contract-tested against Nexterm v1.2.2-BETA routes. The original 0.1.0 entry/folder/identity tool names remain available.

The adapter intentionally does not mirror every Nexterm endpoint. Endpoints that require plaintext credential material, return newly generated credentials, mutate authentication/authorization, or represent interactive transports are excluded rather than weakened into an unsafe generic tool.

Coverage

Explicit exclusions

The following Nexterm API areas are not exposed as normal MCP tools in 0.2.0:

• generic/raw HTTP or arbitrary Nexterm API requests;
• Nexterm API-key management;
• account password, TOTP, passkey and authentication-provider management;
• user and permission administration;
• organization invitations, member removal, permission mutation, invitation response and leave actions;
• identity credential create/update/delete/move;
• Proxmox integration create/update because the API requires a plaintext password;
• backup-provider create/update because the API may require a plaintext password;
• engine registration/token generation or token regeneration;
• audit recording binary download;
• interactive terminal, connection, SFTP, WebSocket, share and session transports;
• Nexterm AI operations.

These are security or protocol boundaries, not missing raw escape hatches. A future credential-mutating tool should use a non-model-visible delivery mechanism such as private local files rather than accepting passwords or private keys as MCP arguments.

Security defaults

• The API key is read from a private local file and never accepted as a tool argument.
• API-key files must be regular non-symlink files with no group or other permissions.
• Common credential-shaped response fields are removed recursively before MCP output is returned.
• HTTP error bodies are not echoed into MCP errors.
• All mutation tools fail closed unless NEXTERM_MUTATIONS_ENABLED=true.
• Delete, restore, stop and shutdown operations that can cause irreversible or disruptive effects are marked destructive in MCP annotations.
• There is no raw request tool.

See SECURITY.md for the full security model.

Requirements

• Python 3.12+
• Nexterm with API-key support (v1.2.2-BETA or a compatible newer release)
• An MCP client that supports stdio servers

Configuration

Example MCP registration:

{
  "mcpServers": {
    "nexterm": {
      "command": "nexterm-mcp",
      "env": {
        "NEXTERM_BASE_URL": "https://nexterm.example.com",
        "NEXTERM_API_KEY_FILE": "/run/secrets/nexterm-api-key",
        "NEXTERM_MUTATIONS_ENABLED": "false"
      }
    }
  }
}

Use an MCP gateway or client-side allowlist when a consumer only needs a subset of the 89 tools. In particular, keep mutations and administrative reads away from consumers that only need entry discovery.

Entry model

Entry create/update supports the currently validated Nexterm v1.2.2-BETA connection fields rather than an arbitrary config object:

• name, entry_type, renderer, icon;
• protocol: ssh, telnet, rdp, vnc, sftp, ftp, ftps, demo;
• ip, port, keyboard_layout;
• monitoring_enabled;
• node_name, vmid;
• rdp_security;
• jump_host_ids;
• mac_address, wake_on_lan_enabled, wol_broadcast_address;
• identity_ids, folder_id, organization_id.

Partial entry updates first read the current entry and merge changed connection fields into the existing Nexterm config object. This preserves fields that a compatible Nexterm release may already store but that the caller did not ask to change.

Compatibility

The API contract currently follows Nexterm v1.2.2-BETA. Nexterm is still evolving, so a newer release may add or change routes or validation fields. nexterm_status reports the server version returned by Nexterm, while tests pin the adapter's known route contract.

The adapter deliberately relies on Nexterm's own authorization checks. A Nexterm API key acts with the permissions of its linked Nexterm account; the MCP server does not invent a second authorization model.

Development

python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest

Build a wheel with:

python -m pip wheel --no-deps --wheel-dir dist .

License

MIT