Setup

The server is published as @calimero-network/mero-mcp and runs over stdio, so there is nothing to deploy and no port to pick. Your MCP client spawns it, and it connects to a node lazily on the first tool call.

Prerequisites

Node.js 20 or newer. npx comes with it.
A running Calimero node — start one in the Calimero desktop app, or run merod directly.
An application installed on that node. From the app registry, or with the install_application tool once the server is up.
A context for that application.

Installing an application does not create a context, and most of the app tools need one to run against. Create one in the desktop app, or call create_context — see contexts and namespaces.

Let the agent wire it up

Paste this into any AI harness (Claude Code, Cursor, Codex CLI, Claude Desktop, Zed, …) and let it register the server for you. It tells the harness how to detect whether you even need credentials, which is the part that is easy to get wrong by hand:

Set up the mero-mcp MCP server for me.

It is on npm as @calimero-network/mero-mcp and runs over stdio. Register a
server named "calimero" that runs `npx -y @calimero-network/mero-mcp`.

In Claude Code that is one command:
  claude mcp add -s local calimero -- npx -y @calimero-network/mero-mcp

Otherwise find where your own harness keeps its MCP server config - Claude
Desktop uses claude_desktop_config.json, Cursor/Windsurf use .cursor/mcp.json,
Codex CLI uses ~/.codex/config.toml (same fields, TOML syntax).
(If I tell you I'm running this from a local clone instead of the published
package, use `node /abs/path/to/dist/index.js` as the command instead, with
no args.)

Before adding any environment variables, check whether
~/.config/calimero/mcp/agent.json exists on my machine. If it does, register
the server with no env vars at all - that file is a handoff from the
Calimero desktop app and the server picks up the node URL and credentials
from it automatically. If it does not exist, ask me for CALIMERO_NODE_URL
(the node to connect to) and how I want to authenticate - either
CALIMERO_AUTH_TOKEN (plus optional CALIMERO_REFRESH_TOKEN), or
CALIMERO_USERNAME plus CALIMERO_PASSWORD - and set those instead. If I don't
know, ask me to check whether the node has auth enabled at all before
assuming I need any of this.

Once it's registered, verify the connection yourself: call the node_status
tool, then list_applications, then list_contexts. Report back what each one
returned.

If anything fails, don't guess - show me the server's stderr output so we
can see the actual error.

Wire it up by hand

The config is the same everywhere; only the file and its syntax change.

One command, for a server scoped to the current project:

claude mcp add -s local calimero -- npx -y @calimero-network/mero-mcp

Or edit .mcp.json in the project (~/.claude.json for a user-wide server):

{
  "mcpServers": {
    "calimero": {
      "command": "npx",
      "args": ["-y", "@calimero-network/mero-mcp"]
    }
  }
}

{
  "mcpServers": {
    "calimero": {
      "command": "npx",
      "args": ["-y", "@calimero-network/mero-mcp"]
    }
  }
}

Restart Claude Desktop after editing — it reads this file at launch.

{
  "mcpServers": {
    "calimero": {
      "command": "npx",
      "args": ["-y", "@calimero-network/mero-mcp"]
    }
  }
}

Same fields, TOML syntax:

[mcp_servers.calimero]
command = "npx"
args = ["-y", "@calimero-network/mero-mcp"]

Which file, at a glance

Client	Config location
Claude Code	`.mcp.json` in the project, or `~/.claude.json` for a user-wide server
Claude Desktop	`claude_desktop_config.json`
Cursor / Windsurf	`.cursor/mcp.json`
Codex CLI	`~/.codex/config.toml`, as `[mcp_servers.calimero]`

Running from a clone

Building locally gives you the same server without the npm round trip — use this when you are changing the server itself:

git clone https://github.com/calimero-network/mero-mcp
cd mero-mcp
npm install
npm run build

Then point the client at the built entrypoint, with no arguments:

{
  "mcpServers": {
    "calimero": {
      "command": "node",
      "args": ["/abs/path/to/mero-mcp/dist/index.js"]
    }
  }
}

Do you need environment variables?

Usually not. The server discovers a node and an identity on its own:

If the desktop app has written a handoff file (~/.config/calimero/mcp/agent.json, from its Connect AI agent action), the server reads both the node URL and a token from it — register with no environment variables at all.
Otherwise it scans ~/.calimero for node configs and probes common local ports.

Set variables when that is not enough — a remote node, several local nodes, or a node with auth enabled and no handoff file. The full list is in configuration; the resolution order is in node discovery and authentication.

Verify it end to end: your first session.