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:
- Remote endpoint (OAuth) —
https://nodepal.net/mcpfor AI apps with remote connectors (no API token to paste). - 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: Beareron every request. Missing or invalid returns401withWWW-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, else403.GETandDELETEanswer405;Mcp-Session-Idis ignored and never sent.MCP-Protocol-Version/Mcp-Methodchecks 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'sFRONTEND_URL),NODEPAL_INTERNAL_API(defaulthttp://backend:8000),NODEPAL_MCP_PORT(default8080). - 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
- Sign in at https://nodepal.net and open Account > API & agents (
/app/account/api). - 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.
- 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 arenull.console_tail: takeslevel(all|warn|error; a stack trace stays with its error),since(start= the output of the last start;since_start_known: falsewhen the portal did not see it begin), andgrep(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,diagnosticsin the server's environment (unknown names are an error). - remote:
https://nodepal.net/mcp?toolsets=servers,console,diagnostics(unknown names return400).
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nodepal_mcp-0.2.1.tar.gz | 70.9 kB | Without provenance | Details for nodepal_mcp-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nodepal_mcp-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for nodepal_mcp-0.2.1-py3-none-any.whl |
Total release size: 136.3 kB
Release files / nodepal_mcp-0.2.1.tar.gz
| Download URL | nodepal_mcp-0.2.1.tar.gz |
|---|---|
| Size | 70.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb011888ec32587a2ce93df149a0363b1fd4c2e68f0c786c536c85146c408982
|
|
BLAKE2b-256 checksum How to use checksums |
e7e192fada0c058f0ecc7ca791b5c5c74de7cbdeeedc5ff780f64cee9d724b62
|
| 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.1-py3-none-any.whl
| Download URL | nodepal_mcp-0.2.1-py3-none-any.whl |
|---|---|
| Size | 65.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4067307b61345ab9e5d9894a6f6aff5680c27f01e1548269c46e46eb2f9618f9
|
|
BLAKE2b-256 checksum How to use checksums |
9b03ffce13f6eec957a7362891a615e135539b12a301e3ef6f5d5c76348ee9a2
|
| 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.1
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.