nexterm-mcp
Provides a safe subset of Proxmox integration management through Nexterm, including reading, deleting, syncing, and controlling Proxmox entries (start/stop/shutdown).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nexterm-mcp Show me all my server entries"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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. See the complete docs/tools.md reference for access classification, destructive semantics, inputs and purpose.
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.
Related MCP server: MCP Dockerized Server
Coverage
Area | Coverage | Notes |
Service/account status | Supported |
|
Entries | Broad | List, recent, get, create, update, delete, duplicate, typed SSH import, reposition and Wake-on-LAN. |
Folders | Full resource CRUD | List, create, update/move and delete. |
Identities | Metadata read only | Credential-bearing identity create/update/delete/move is intentionally excluded. |
Tags | Full | List, CRUD, assign/unassign and per-entry tag discovery. |
Organizations | Resource/settings + read | List/get/CRUD, member reads, member-permission reads and session settings. Membership and permission mutations are excluded. |
Scripts | Broad | List/search, all/source discovery, get, CRUD and reposition. Script content is model-visible. |
Snippets | Broad | List/source discovery, get, CRUD and reposition. Command content is model-visible. |
Themes | Full resource management | List/get/CSS, CRUD and active-theme selection. |
Sources | Full | List/get/validate/CRUD and synchronization actions. |
Monitoring | Full | Overview, global settings and server/integration history for Nexterm's |
Audit | Broad | Log query, metadata and organization audit settings. Binary recording download is excluded. |
Backup | Broad safe subset | File listing/deletion, settings, storage, provider deletion, backup listing/create/restore. Provider create/update is excluded because it accepts plaintext passwords. |
Proxmox integrations | Safe subset | Read, delete, sync and entry start/stop/shutdown. Create/update is excluded because Nexterm requires a plaintext password. |
Engines | Metadata read only | Token-generating create/regenerate operations are intentionally excluded. |
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.
Feedback and contributions
Use GitHub Issues for bug reports and feature requests and pull requests for proposed changes. See CONTRIBUTING.md for the development workflow, test requirements, and change expectations. Security issues must follow the private process in SECURITY.md.
User-visible release changes are summarized in CHANGELOG.md.
Requirements
Python 3.12+
Nexterm with API-key support (
v1.2.2-BETAor a compatible newer release)An MCP client that supports stdio servers
Configuration
Variable | Required | Default | Meaning |
| yes | - | Nexterm base URL, for example |
| yes | - | Absolute path to a private mode- |
| no |
| HTTP timeout, maximum 120 seconds. |
| no |
| Enables all non-read-only tools when set to |
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.
Running a release
Accepted releases publish a reproducible wheel and SHA256SUMS. For v0.2.0:
uvx --python 3.12 \
--from https://github.com/X1pheR/nexterm-mcp/releases/download/v0.2.0/nexterm_mcp-0.2.0-py3-none-any.whl \
nexterm-mcpProvide the same environment variables shown above. Release tags are the stable source snapshot; the wheel is the runtime artifact.
Running from source
The repository includes uv.lock so source deployments can use a reproducible dependency set without installing the package globally.
uv sync --frozen
NEXTERM_BASE_URL=https://nexterm.example.com \
NEXTERM_API_KEY_FILE=/run/secrets/nexterm-api-key \
uv run --frozen nexterm-mcpMutations remain disabled in this example. Set NEXTERM_MUTATIONS_ENABLED=true only on an MCP surface where state-changing Nexterm tools are intentionally permitted.
A stdio gateway can launch the checkout directly as well:
{
"command": "uv",
"args": ["run", "--frozen", "--directory", "/path/to/nexterm-mcp", "nexterm-mcp"],
"env": {
"NEXTERM_BASE_URL": "https://nexterm.example.com",
"NEXTERM_API_KEY_FILE": "/run/secrets/nexterm-api-key",
"NEXTERM_MUTATIONS_ENABLED": "false"
}
}Entry model
Entry create/update uses typed connection fields rather than an arbitrary config object; the exact inputs are listed in docs/tools.md. Partial updates first read the current entry and merge only requested 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
With uv:
uv sync --frozen --extra test
uv run --frozen --extra test pytestA conventional virtual environment remains supported:
python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytestBuild a wheel with:
uv buildGitHub CI uses the frozen dependency set for package-version verification, tests and wheel builds. Dependabot maintains locked dependencies and pinned workflow dependencies within accepted compatibility ranges. OpenSSF Scorecard runs on main and weekly and publishes its public result for independent repository-security review.
Normal development does not publish a release. An accepted strict SemVer tag (vMAJOR.MINOR.PATCH) triggers the release workflow, which verifies the exact tag/source/package version, reruns frozen tests, proves two independent wheel builds are byte-identical, generates signed GitHub/Sigstore build provenance, creates a draft release, attaches the wheel, SHA256SUMS and provenance bundle, and only then publishes the release.
License
MIT
Available Tools
89 toolsnexterm_assign_tagC
Assign a tag to an entry.
Inputs: tag_id (required), entry_id (required).
nexterm_create_backupB
Create a backup using an existing configured provider.
Inputs: provider_id (required).
nexterm_create_entryC
Create a Nexterm server entry using typed connection fields.
Inputs: ip (required), name (required), icon, port, +14 more.
nexterm_create_folderC
Create a Nexterm folder.
Inputs: name (required), parent_id, organization_id.
nexterm_create_organizationD
Create a Nexterm organization.
Inputs: name (required), description.
nexterm_create_scriptC
Create a Nexterm script. Script content is model-visible by design.
Inputs: name (required), content (required), os_filter, description, +1 more.
nexterm_create_snippetC
Create a Nexterm command snippet. Command content is model-visible by design.
Inputs: name (required), command (required), os_filter, description, +1 more.
nexterm_create_sourceC
Create and initially sync a Nexterm content source.
Inputs: url (required), name (required).
nexterm_create_tagC
Create a Nexterm tag.
Inputs: name (required), color (required).
nexterm_create_themeC
Create a custom Nexterm CSS theme.
Inputs: css (required), name (required), description.
nexterm_delete_backup_fileBDestructive
Permanently delete a Nexterm recording or log file.
Inputs: filename (required), file_type (required).
nexterm_delete_backup_providerBDestructive
Permanently delete a configured backup provider. Provider credential creation/update is intentionally not exposed.
Inputs: provider_id (required).
nexterm_delete_entryCDestructive
Permanently delete a Nexterm entry.
Inputs: entry_id (required).
nexterm_delete_folderCDestructive
Permanently delete a Nexterm folder according to Nexterm's folder deletion semantics.
Inputs: folder_id (required).
nexterm_delete_integrationBDestructive
Permanently delete a Nexterm integration.
Inputs: integration_id (required).
nexterm_delete_organizationCDestructive
Permanently delete a Nexterm organization.
Inputs: organization_id (required).
nexterm_delete_scriptCDestructive
Permanently delete a Nexterm script.
Inputs: script_id (required), organization_id.
nexterm_delete_snippetCDestructive
Permanently delete a Nexterm snippet.
Inputs: snippet_id (required), organization_id.
nexterm_delete_sourceBDestructive
Permanently delete a source and its synchronized content.
Inputs: source_id (required).
nexterm_delete_tagBDestructive
Permanently delete a Nexterm tag.
Inputs: tag_id (required).
nexterm_delete_themeBDestructive
Permanently delete a custom Nexterm theme.
Inputs: theme_id (required).
nexterm_duplicate_entryC
Duplicate an existing Nexterm entry.
Inputs: entry_id (required).
nexterm_get_active_theme_cssARead-onlyIdempotent
Get CSS for the configured account's active theme.
Inputs: no named parameters.
nexterm_get_audit_logsCRead-onlyIdempotent
Query Nexterm audit logs with bounded pagination and filters.
Inputs: limit, action, offset, end_date, +3 more.
nexterm_get_audit_metadataBRead-onlyIdempotent
Get available audit actions and resource metadata.
Inputs: no named parameters.
nexterm_get_backup_settingsARead-onlyIdempotent
Get backup settings and sanitized provider metadata.
Inputs: no named parameters.
nexterm_get_backup_storageBRead-onlyIdempotent
Get Nexterm backup storage statistics.
Inputs: no named parameters.
nexterm_get_entryCRead-onlyIdempotent
Get one Nexterm entry by ID.
Inputs: entry_id (required).
nexterm_get_integrationBRead-onlyIdempotent
Get sanitized metadata for one Nexterm integration.
Inputs: integration_id (required).
nexterm_get_integration_monitoringCRead-onlyIdempotent
Get monitoring history for an integration.
Inputs: target_id (required), time_range.
nexterm_get_monitoringBRead-onlyIdempotent
Get current monitoring overview for accessible servers.
Inputs: no named parameters.
nexterm_get_monitoring_settingsARead-onlyIdempotent
Get global Nexterm monitoring settings.
Inputs: no named parameters.
nexterm_get_organizationCRead-onlyIdempotent
Get organization details.
Inputs: organization_id (required).
nexterm_get_organization_audit_settingsCRead-onlyIdempotent
Get audit settings for an organization.
Inputs: organization_id (required).
nexterm_get_organization_member_permissionsBRead-onlyIdempotent
Read one organization's effective member permissions.
Inputs: account_id (required), organization_id (required).
nexterm_get_organization_session_settingsCRead-onlyIdempotent
Read organization live-session settings.
Inputs: organization_id (required).
nexterm_get_scriptBRead-onlyIdempotent
Get one script, optionally in an organization scope.
Inputs: script_id (required), organization_id.
nexterm_get_server_monitoringCRead-onlyIdempotent
Get monitoring history for a server entry.
Inputs: target_id (required), time_range.
nexterm_get_snippetCRead-onlyIdempotent
Get one snippet, optionally in an organization scope.
Inputs: snippet_id (required), organization_id.
nexterm_get_sourceCRead-onlyIdempotent
Get one Nexterm content source.
Inputs: source_id (required).
nexterm_get_themeCRead-onlyIdempotent
Get theme metadata and content.
Inputs: theme_id (required).
nexterm_get_theme_cssCRead-onlyIdempotent
Get CSS for one theme.
Inputs: theme_id (required).
nexterm_import_ssh_configC
Import a typed batch of SSH server definitions into a Nexterm folder.
Inputs: servers (required), folder_id.
nexterm_list_all_scriptsARead-onlyIdempotent
List all accessible scripts across personal, organization and source scopes.
Inputs: no named parameters.
nexterm_list_backup_filesCRead-onlyIdempotent
List Nexterm recording or log files available to the backup subsystem.
Inputs: file_type (required).
nexterm_list_enginesARead-onlyIdempotent
List Nexterm engine metadata. Token-bearing engine mutations are intentionally excluded.
Inputs: no named parameters.
nexterm_list_entriesBRead-onlyIdempotent
List accessible Nexterm entries.
Inputs: no named parameters.
nexterm_list_entry_tagsCRead-onlyIdempotent
List tags assigned to an entry.
Inputs: entry_id (required).
nexterm_list_foldersBRead-onlyIdempotent
List accessible Nexterm folders.
Inputs: no named parameters.
nexterm_list_identitiesARead-onlyIdempotent
List accessible Nexterm identity metadata. Credential material is never returned.
Inputs: no named parameters.
nexterm_list_organization_membersCRead-onlyIdempotent
List members of an organization.
Inputs: organization_id (required).
nexterm_list_organizationsARead-onlyIdempotent
List organizations accessible to the configured Nexterm account.
Inputs: no named parameters.
nexterm_list_pending_invitationsARead-onlyIdempotent
List pending organization invitations for the configured account.
Inputs: no named parameters.
nexterm_list_provider_backupsBRead-onlyIdempotent
List backups stored by one configured provider.
Inputs: provider_id (required).
nexterm_list_scriptsBRead-onlyIdempotent
List or search accessible scripts, optionally scoped to an organization.
Inputs: search, organization_id.
nexterm_list_script_sourcesCRead-onlyIdempotent
List source-backed scripts.
Inputs: no named parameters.
nexterm_list_snippetsBRead-onlyIdempotent
List all accessible Nexterm snippets.
Inputs: no named parameters.
nexterm_list_snippet_sourcesCRead-onlyIdempotent
List source-backed snippets.
Inputs: no named parameters.
nexterm_list_sourcesBRead-onlyIdempotent
List configured Nexterm content sources.
Inputs: no named parameters.
nexterm_list_tagsBRead-onlyIdempotent
List personal Nexterm tags.
Inputs: no named parameters.
nexterm_list_themesARead-onlyIdempotent
List available Nexterm themes.
Inputs: no named parameters.
nexterm_recent_entriesCRead-onlyIdempotent
List recently connected Nexterm entries.
Inputs: limit.
nexterm_reposition_entryC
Reposition or move a Nexterm entry.
Inputs: entry_id (required), placement (required), folder_id, target_id, +1 more.
nexterm_reposition_scriptC
Reorder a Nexterm script relative to another script.
Inputs: script_id (required), target_id (required), organization_id.
nexterm_reposition_snippetC
Reorder a Nexterm snippet relative to another snippet.
Inputs: target_id (required), snippet_id (required), organization_id.
nexterm_restore_backupBDestructive
Restore a backup. Nexterm documents that this initiates a server restart.
Inputs: backup_name (required), provider_id (required).
nexterm_set_active_themeA
Set an active theme, or pass null to clear the active theme.
Inputs: theme_id (required).
nexterm_shutdown_integration_entryBDestructive
Request guest shutdown for the external resource represented by an integration entry.
Inputs: entry_id (required).
nexterm_start_integration_entryC
Start the external resource represented by an integration entry.
Inputs: entry_id (required).
nexterm_statusARead-onlyIdempotent
Verify authenticated Nexterm API access and report adapter status without exposing credentials.
Inputs: no named parameters.
nexterm_stop_integration_entryCDestructive
Stop the external resource represented by an integration entry.
Inputs: entry_id (required).
nexterm_sync_all_sourcesA
Trigger synchronization for all enabled content sources.
Inputs: no named parameters.
nexterm_sync_integrationC
Synchronize an existing Nexterm integration.
Inputs: integration_id (required).
nexterm_sync_sourceC
Synchronize one Nexterm content source.
Inputs: source_id (required).
nexterm_unassign_tagC
Remove a tag assignment from an entry.
Inputs: tag_id (required), entry_id (required).
nexterm_update_backup_settingsC
Update Nexterm backup schedule and inclusion settings.
Inputs: retention, include_logs, include_database, schedule_interval, +1 more.
nexterm_update_entryC
Update typed fields on an entry while preserving unmodified Nexterm config fields.
Inputs: entry_id (required), ip, icon, name, +16 more.
nexterm_update_folderC
Update or move a Nexterm folder.
Inputs: folder_id (required), name, parent_id, organization_id.
nexterm_update_monitoring_settingsC
Update global Nexterm monitoring settings.
Inputs: batch_size, status_interval, connection_timeout, monitoring_enabled, +3 more.
nexterm_update_organizationC
Update organization name or description.
Inputs: organization_id (required), name, description.
nexterm_update_organization_audit_settingsC
Update audit settings for an organization.
Inputs: organization_id (required), enable_session_recording, recording_retention_days, enable_ai_operation_audit, +8 more.
nexterm_update_organization_session_settingsC
Update organization live-session settings.
Inputs: organization_id (required), enable_live_session_sharing (required).
nexterm_update_scriptC
Update a Nexterm script. Script content is model-visible by design.
Inputs: script_id (required), name, content, os_filter, +2 more.
nexterm_update_snippetD
Update a Nexterm command snippet.
Inputs: snippet_id (required), name, command, os_filter, +2 more.
nexterm_update_sourceC
Update a Nexterm content source.
Inputs: source_id (required), url, name, enabled.
nexterm_update_tagC
Update a Nexterm tag.
Inputs: tag_id (required), name, color.
nexterm_update_themeC
Update a custom Nexterm CSS theme.
Inputs: theme_id (required), css, name, description.
nexterm_validate_sourceBRead-onlyIdempotent
Validate a source URL and report discovered content counts.
Inputs: url (required).
nexterm_wake_entryB
Send Wake-on-LAN for an entry using its configured WOL settings.
Inputs: entry_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 89 tools
Most tools target a distinct resource and action, but the large surface creates real overlap among list variants such as list_scripts/list_all_scripts/list_script_sources and list_snippets/list_snippet_sources. Theme CSS and source/snippet source terminology can also be confused without careful reading.
Every tool uses the nexterm_ prefix followed by a predictable verb_noun pattern: list_*, get_*, create_*, update_*, delete_*, sync_*, etc. The convention is consistently applied across all domains.
89 tools is far beyond a well-scoped MCP surface, even for a broad server-management platform. The toolset is split across many domains, but the count is extreme and makes discovery and selection cumbersome.
Core domains like entries, folders, tags, organizations, scripts, snippets, themes, sources, monitoring, audit, and backups have substantial coverage. However, notable lifecycle gaps remain for identities, integrations, organization members/invitations, and engines, several of which are read-only or partially exposed.
Maintenance
Related MCP Connectors
The official MCP Server for the Mux API
MCP server for interacting with the Supabase platform
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Public read-only MCP server for Genvernium product and developer resources.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.-
- FlicenseNot gradedqualityDmaintenanceA minimal, containerized MCP server that exposes a Streamable HTTP transport with API key authentication, allowing secure access to MCP endpoints.-
- AlicenseAqualityDmaintenanceMCP server for creating, listing, updating, deleting memos, and managing attachments via the Memos API.1223 npmMIT
- FlicenseAqualityBmaintenanceMCP server for the Gripp API, enabling CRUD operations on Gripp entities with built-in confirmation safety for mutations.91-