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: Append ?toolsets=... to narrow the exposed tools (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 toolset names to limit which tools are exposed.

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)

Exposing every tool uses a lot of model context. You can limit them to the domains you need; the names match the modules under src/nodepal_mcp/tools/: account, groups, members, nodes, servers, fit, console, diagnostics, backups, worlds, content, modpacks, storage, configs. Default: all.

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

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.2.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.2.0
File Size Uploaded Provenance Actions
nodepal_mcp-0.2.0.tar.gz 68.2 kB Without provenance Details for nodepal_mcp-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 131.8 kB

Release files / nodepal_mcp-0.2.0.tar.gz

Download URL nodepal_mcp-0.2.0.tar.gz
Size 68.2 kB
Tags Source
SHA-256 checksum
How to use checksums
35597be5a79d64202d31df9acc2512db176e25e83e17f640f2fbdcedc8c8faf1
BLAKE2b-256 checksum
How to use checksums
4a11f591a9536b0674d7a0579e0aa65586797b77383dff316d21935b1d501dc5
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.2.0-py3-none-any.whl

Download URL nodepal_mcp-0.2.0-py3-none-any.whl
Size 63.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ec74c5d0d482bf5f2767577c32949ee127d2e03db3e4c6a0b10255ec4ba3553
BLAKE2b-256 checksum
How to use checksums
62b5a5d2a8f06b7cd4271b7d10449e5f8dfa5afa7099d511bed736f6943543ae
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.2.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