nodus-mcp-server
Status: published on PyPI.
An MCP server that connects AI assistants to the Nodus language runtime — giving them persistent memory, sandboxed code execution, and checkpoint/resume orchestration workflows, all powered by .nd scripts running on the Nodus VM.
Supports Claude Desktop (stdio) and ChatGPT Desktop (HTTP/SSE).
Tools
| Tool | What it does |
|---|---|
nodus_remember |
Store a fact in persistent memory with optional tags |
nodus_recall |
Search memory by free-text query and/or tags |
nodus_forget |
Delete a memory entry by ID |
nodus_run_goal |
Run a built-in Nodus goal (structured multi-step result) |
nodus_run_workflow |
Run a built-in Nodus workflow (returns a graph_id for resuming) |
nodus_resume_workflow |
Resume a workflow from a checkpoint using its graph_id |
nodus_exec |
Execute arbitrary Nodus code in a sandbox (no file I/O, no network, no subprocess, no environment variables, 10 s timeout) |
Requirements
- Python ≥ 3.10
- pipx (recommended — keeps the server in its own isolated environment)
- Claude Desktop or ChatGPT Desktop (the downloadable apps, not browser versions)
Install
pipx install nodus-mcp-server
Claude Desktop setup
1. Find your config file
| Setup | Config path |
|---|---|
| Standard install | %APPDATA%\Claude\claude_desktop_config.json |
| Windows Store app | %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
2. Add the server
{
"mcpServers": {
"nodus": {
"command": "nodus-mcp-server",
"args": ["--stdio"]
}
}
}
If nodus-mcp-server isn't on your PATH, use the full path to the executable. On Windows with pipx that's typically C:\Users\<you>\.local\bin\nodus-mcp-server.exe.
3. Restart Claude Desktop
The seven nodus_* tools will appear when you click the tools icon (the + button or tool picker) in a new conversation.
How to use
Memory
Store anything you want Claude to remember across conversations:
Use nodus_remember to store: "Project deadline is 2026-07-01" with tags ["project", "deadlines"]
Retrieve it later:
Use nodus_recall to find memories tagged "deadlines"
Or search by content:
Use nodus_recall to find memories about "deadline"
Memory is stored in a local SQLite database at ~/.nodus-mcp-server/data/memory.db and persists across upgrades.
Sandboxed code execution
Run Nodus (.nd) code in a fully sandboxed runtime:
Use nodus_exec to run: print("Hello from Nodus!")
The sandbox enforces: no file I/O, no network, no subprocess, no environment variables. Use print() to surface results — top-level return values are not captured.
Goals (structured multi-step tasks)
Goals run a fixed sequence of named steps and return each step's result:
Use nodus_run_goal with name "summarize" and params {"text": "your text here"}
Built-in goals:
| Goal | Params | What it does |
|---|---|---|
summarize |
{text} |
Counts characters, classifies size (short/medium/long) |
pipeline |
{items, label} |
Validates a list and produces a labelled report |
Workflows (checkpoint/resume orchestration)
Workflows are like goals but support checkpoints — they can be paused and resumed from a saved state:
Use nodus_run_workflow with name "research" and params {"topic": "LLM context windows"}
The response includes a graph_id. Use it to resume the workflow later:
Use nodus_resume_workflow with graph_id "g_abc123" (and optionally a checkpoint label)
Built-in workflows:
| Workflow | Params | What it does |
|---|---|---|
research |
{topic} |
Two-step plan + execute workflow with checkpoints at each step |
Adding your own goals and workflows
Goals and workflows are .nd files (Nodus source) placed in the goals/ or workflows/ directory of the installed package. The file should only define the goal or workflow — the server calls it for you.
// goals/my_goal.nd
goal my_goal {
step process {
if (input_text == nil) { throw "missing required param: input_text" }
let result = len(input_text)
return {"length": result, "has_content": result > 0i}
}
}
Then call it:
{"name": "my_goal", "params": {"input_text": "hello"}}
For a goal, params are injected as top-level variables in the .nd execution context. Check nil before using them — missing params surface as nil, not an error, unless you throw explicitly.
A workflow declares its params instead, so they are stored with the run and restored when it resumes. A missing or unknown param is an error:
// workflows/my_workflow.nd
workflow my_workflow(input_text) {
step process {
checkpoint "processed"
return {"length": len(input_text)}
}
}
See the Nodus language guide for the full .nd syntax reference.
About Nodus
The goals, workflows, and nodus_exec sandbox all run on the Nodus VM — a lightweight, embeddable language runtime designed for AI-native orchestration. Nodus scripts (.nd files) define the step logic; the MCP server wires them to Claude over the Model Context Protocol.
This package is part of the Nodus ecosystem — a family of companion libraries built around the nodus-lang runtime (MCP and A2A servers, an SDK, memory and workflow engines, and more; see the ecosystem overview). The runtime's own suite runs this server's tests on every release, so an upstream change that would break it is caught before it ships.
Architecture
server.py — MCP tool definitions, NodusRuntime setup, request dispatch
runner.py — goal/workflow execution via ModuleLoader + VM
memory_store.py — SQLite-backed thread-safe memory store
goals/ — .nd goal definitions (bundled + custom)
workflows/ — .nd workflow definitions (bundled + custom)
~/.nodus-mcp-server/data/memory.db — SQLite DB (persists across upgrades)
ChatGPT Desktop setup
This server has no authentication. Anyone who can reach its URL can use every tool: read, change and delete your memory, and run code in the
nodus_execsandbox. Do not publish the URL, and stop the tunnel when you are not using it. By default--httplistens only on127.0.0.1.
ChatGPT requires a public HTTPS URL (not localhost). Use ngrok to expose the server.
1. Start the HTTP server
nodus-mcp-server --http --port 8765
This prints:
[nodus-mcp-server] HTTP listening on http://127.0.0.1:8765/mcp
[nodus-mcp-server] Point ChatGPT / your MCP client at: http://127.0.0.1:8765/mcp
2. Expose via ngrok
ngrok http --url=<your-static-domain>.ngrok.io 8765
Keep both terminals open while using ChatGPT, and close them when you finish.
3. Connect in ChatGPT Desktop
- Click your profile icon → Settings → Apps
- Go to Advanced Settings → enable Developer Mode
- Click Create App (or Connect more)
- Enter a name (e.g.
Nodus), description, and base URL:https://<your-static-domain>.ngrok.io/mcp
4. Use in a chat
Open a new chat → click + → More → Developer Mode → enable your Nodus app. The seven nodus_* tools are now available.
Note: Memory is shared with the Claude Desktop instance (same SQLite database at
~/.nodus-mcp-server/data/memory.db).
Upgrading
Stop-Process -Name "nodus-mcp-server" -Force # Windows — close before reinstalling
pipx install nodus-mcp-server --force
Then restart Claude Desktop / ChatGPT Desktop.
Development
git clone https://github.com/Masterplanner25/nodus-mcp-server
cd nodus-mcp-server
python -m pip install . mcp pytest httpx
python -m pytest -q
CI runs the suite across a matrix of OS (Ubuntu, Windows), Python (3.10 and 3.13 — the ends of requires-python), and the mcp SDK (1.x and 2.x, since the server branches on the SDK major). A separate job builds the wheel and completes a real initialize handshake against the installed server. main is branch-protected: changes land through a branch, a pull request, and green CI.
License
MIT
Metadata
Release files for nodus-mcp-server 0.1.16
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 |
|---|---|---|---|---|
| nodus_mcp_server-0.1.16.tar.gz | 23.3 kB | Without provenance | Details for nodus_mcp_server-0.1.16.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nodus_mcp_server-0.1.16-py3-none-any.whl | Python 3 | none | any | Details for nodus_mcp_server-0.1.16-py3-none-any.whl |
Total release size: 39.7 kB
Release files / nodus_mcp_server-0.1.16.tar.gz
| Download URL | nodus_mcp_server-0.1.16.tar.gz |
|---|---|
| Size | 23.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
19ea7af4fb5876c499fb2300e2db7147854aae867883f1223fce4d528ac4f76a
|
|
BLAKE2b-256 checksum How to use checksums |
7811094e8178194532fe40d1e00992bf9429c5fd295d3a58c3af593f943c9b94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / nodus_mcp_server-0.1.16-py3-none-any.whl
| Download URL | nodus_mcp_server-0.1.16-py3-none-any.whl |
|---|---|
| Size | 16.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
190667eaef382496683305800991d00794d54357121fda19ac3deabebb8b4a86
|
|
BLAKE2b-256 checksum How to use checksums |
4297ccf230b1559c412b3f06d7c00e8d6e29fd37a5d47dd66c76ac4730e0217b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for nodus-mcp-server 0.1.16
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.