nodus-mcp-server 0.1.11

MCP server powered by the Nodus orchestration runtime

nodus-mcp-server

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, 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. 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"}}

Input 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.

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.

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

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.

3. Connect in ChatGPT Desktop

1. Click your profile icon → Settings → Apps
2. Go to Advanced Settings → enable Developer Mode
3. Click Create App (or Connect more)
4. 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.

License

MIT