Skip to main content

nodepal-mcp

An MCP server that lets AI agents manage your NodePal Minecraft servers through the portal API: check the PCs hosting servers, find a modpack, check it fits, create the server, start it, add mods, and back it up.

You can connect in two ways:

  1. Remote endpoint (OAuth) — https://nodepal.net/mcp for AI apps with remote connectors (no API token to paste).
  2. Local stdio (uvx nodepal-mcp) — runs on your PC for desktop and terminal AI apps, using a personal API token (NODEPAL_TOKEN). Also supports local file uploads.

Remote endpoint (https://nodepal.net/mcp)

For AI apps that connect to remote MCP servers by URL:

  • URL: https://nodepal.net/mcp
  • Auth: OAuth — sign in with your NodePal account when the AI app asks. There is no API token to copy or paste.
  • Toolsets: by default the endpoint lists about 30 essential tools. Append ?toolsets=all for every tool, or ?toolsets=essential,configs to add domains (see Toolsets).

The remote endpoint exposes the same tools over MCP Streamable HTTP (spec 2026-07-28), stateless, with JSON responses. It runs as its own container (nodepal-mcp --http or NODEPAL_MCP_MODE=http; Docker target runner; port 8080 inside the stack, reached only through the portal's nginx at /mcp).

  • Auth details: Authorization: Bearer on every request. Missing or invalid returns 401 with WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp". The token is checked against the backend (GET <NODEPAL_INTERNAL_API>/api/oauth/token-info, cached up to 30 s by token hash); an OAuth token issued for another resource is refused. Personal API tokens (npl_) work too.
  • The tools call the backend's API with the caller's own token. That is the same system that issued the token, not a pass-through to a third party; the scopes, group limits and approvals of the token apply.
  • Origin: absent (not a browser) is accepted; present it must be the portal's own origin, else 403.
  • GET and DELETE answer 405; Mcp-Session-Id is ignored and never sent. MCP-Protocol-Version / Mcp-Method checks and the 4 MiB body limit are the SDK's. Tools that upload a local file answer that uploads only work in local mode.
  • Server environment: NODEPAL_URL (public address = OAuth issuer, must equal the backend's FRONTEND_URL), NODEPAL_INTERNAL_API (default http://backend:8000), NODEPAL_MCP_PORT (default 8080).
  • The token is never logged; log lines carry a short id (the start of its SHA-256).

Local stdio (uvx nodepal-mcp)

Requires Python 3.10+ or uv (uvx downloads and runs nodepal-mcp in an isolated environment).

Create an API token

  1. Sign in at https://nodepal.net and open Account > API & agents (/app/account/api).
  2. Create a token: give it a name, choose the scopes it needs (see Safety), the groups it may touch (or all of yours), an expiry (30 days by default), and the approval mode.
  3. Copy the token (npl_...). It is shown once.

Configuration is by environment variables:

Variable Meaning
NODEPAL_TOKEN Required in stdio mode. The API token. Never logged or printed by the server.
NODEPAL_URL Optional. Default https://nodepal.net (use http://127.0.0.1:3060 for a local stack).
NODEPAL_MCP_TOOLSETS Optional. Comma-separated toolsets: default essential (about 30 tools); all for every tool; or domain names, combinable (essential,configs).

Desktop and terminal AI app configuration

Generic mcpServers JSON configuration for desktop and terminal AI apps:

{
  "mcpServers": {
    "nodepal": {
      "command": "uvx",
      "args": ["nodepal-mcp"],
      "env": {
        "NODEPAL_TOKEN": "npl_xxx"
      }
    }
  }
}

If you installed the package directly with pip install nodepal-mcp, use "command": "nodepal-mcp" with no "args".

One-click desktop bundle (.mcpb)

The .mcpb desktop bundle wraps uvx nodepal-mcp and asks securely for your NODEPAL_TOKEN during setup. Using the bundle requires uv to be installed on your computer so uvx is available on your PATH.

Tools

Everything a person does with their groups in the portal has a tool, grouped by domain in src/nodepal_mcp/tools/: account, groups, members, nodes, servers, fit, console, diagnostics, backups, worlds, content, modpacks, storage, and configs. Names are verb_object (list_servers, create_world_from_modpack, set_node_p2p, ...). Each tool says in its description what needs a scope or an approval: read < control (power, backups, console) < manage (create/change) < destructive (deletes, restores, roles, ownership: approval_id flow).

Local uploads: upload_modpack, upload_custom_content, import_world_archive, set_group_icon, and set_server_icon take a local file path and only work locally in the stdio server running on your PC (they are disabled on the remote https://nodepal.net/mcp endpoint).

What an agent never gets: sign-in, account and API-token management, admin, node secrets and storage credentials (session only); tokens or links in answers; secret-looking values of config files (shown as ***).

Resources are reported as "unknown" when a PC's daemon has not reported them; nothing is invented. estimate_fit compares a modpack's (estimated) needs with a node's free RAM and disk and answers fits, tight, does_not_fit, or unknown, with reasons.

Diagnosis

  • diagnose_server: one call with the last failed start and its suggested actions, health warnings, the jar inventory (approved on the node, on disk), conflicts, Java required vs configured, and the node/daemon state. Unknown values are null.
  • console_tail: takes level (all|warn|error; a stack trace stays with its error), since (start = the output of the last start; since_start_known: false when the portal did not see it begin), and grep (literal text, up to 100 characters).
  • check_instance: returns the "Check this instance" result your own NodePal Companion reported for a server (file names, mod ids, versions only; never folders), or says how to generate it.
  • Prompts (recipes) list the tools in order and when to ask you: diagnose_server_that_does_not_start, add_mods_safely, create_world_from_modpack_with_seed, move_world_to_another_node, recover_from_bad_backup.

Developer setup and API reference: https://nodepal.net/developers.

Toolsets (fewer tools, less context)

Listing every tool costs about 38k tokens of model context, so by default only the essential set (about 30 tools: get_overview, servers, worlds, backups, console, diagnosis, content, recommended packs) is exposed. The rest is grouped by domain; the names match the modules under src/nodepal_mcp/tools/: account, groups, members, nodes, servers, fit, console, diagnostics, backups, worlds, content, modpacks, storage, configs. Names can be combined: essential,configs, servers,worlds. all exposes every tool.

  • stdio: NODEPAL_MCP_TOOLSETS=all (or essential,configs, servers,console,diagnostics) in the server's environment (unknown names are an error).
  • remote: https://nodepal.net/mcp?toolsets=all (or ?toolsets=essential,configs; unknown names return 400).

Long-running tools (installing packs, backups, uploads) send notifications/progress in stdio mode when the client asks for them. The remote endpoint is stateless with JSON responses, so it has no stream for progress.

Prompts are not affected.

Safety

  • Scopes: read (all reads), control (start/stop/restart, backups), manage (create/change servers, worlds, content), destructive (deletes, restores). Give the agent only what it needs; a read-only token is a fine start.
  • Approval modes for destructive actions: in confirm mode (default) the portal does not execute them; it answers "approval required" with a link. The tool tells the agent to ask you, you approve in the portal, and the agent repeats the call with the approval_id (works once, for exactly that request, for 15 minutes). In free mode they run immediately: only enable it for tokens and agents you fully trust.
  • Revoke a token or disconnect an OAuth app at any time in the portal (/app/account/api); tokens expire on their own (max 1 year).
  • The token is a secret like a password: keep it out of repositories and chats.
  • Account security (password, 2FA, sessions, tokens themselves) can never be reached with a token.

Development

The host has no Python toolchain; everything runs in Docker. From this mcp/ folder (Git Bash):

MSYS_NO_PATHCONV=1 docker build -q --target test -t nodepal-mcp-test .
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd -W):/app" -w /app nodepal-mcp-test sh -c "python -m pytest -q && ruff check ."

To build the PyPI artifacts and .mcpb bundle inside Docker:

sh scripts/build-bundle.sh

mcp-name: net.nodepal/nodepal-mcp

Metadata

Release files for nodepal-mcp 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nodepal-mcp 0.3.0
File Size Uploaded Provenance Actions
nodepal_mcp-0.3.0.tar.gz 78.8 kB Without provenance Details for nodepal_mcp-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nodepal-mcp 0.3.0
File Interpreter ABI Platform Actions
nodepal_mcp-0.3.0-py3-none-any.whl Python 3 none any Details for nodepal_mcp-0.3.0-py3-none-any.whl

Total release size: 147.9 kB

Release files / nodepal_mcp-0.3.0.tar.gz

Download URL nodepal_mcp-0.3.0.tar.gz
Size 78.8 kB
Tags Source
SHA-256 checksum
How to use checksums
cf0407ff70046c45b0598235b8a551c6cca58053b4e25097f9763938d2ee3b34
BLAKE2b-256 checksum
How to use checksums
7652cee644d98924502940d62fffae75213800592a2c8212ec31d754a95494b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / nodepal_mcp-0.3.0-py3-none-any.whl

Download URL nodepal_mcp-0.3.0-py3-none-any.whl
Size 69.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a61d696a43d11b1abf20fcc3061997553c47cd825e7492c96e0f8cfed9a6c28c
BLAKE2b-256 checksum
How to use checksums
5e44d3159edfce28754dde8f4c465c9b04b9ed104b2ffce762fd22b05911528f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for nodepal-mcp 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page