Naumu MCP server

@naumu/mcp

MCP server for Naumu - access your knowledge graph from Claude Code, Cursor, and other AI agents.

This repository is the public home of the published @naumu/mcp package: docs, issues, and releases. Development happens in the Naumu monorepo. Found a bug or want a tool added? Open an issue.

Naumu speaks MCP over two transports:

1. Remote, over OAuth at https://naumu.ai/api/mcp - the recommended path. You sign in through your browser, and there is no API key to create, paste, or keep in sync. This package is not involved.
2. Local stdio, this package, launched on demand with npx and authenticated with an API key. Use it for clients that cannot do browser OAuth: CI jobs, bot and external-agent identities, and older stdio-only harnesses.

Recommended setup: remote MCP over OAuth

Register the server once. The first time a session uses a Naumu tool, your browser opens to sign in and approve access. After that the tools are available in every session.

Claude Code

claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp

--scope user registers the server for your whole machine rather than the current project, so you do not have to repeat it per repository.

Cursor

{
  "mcpServers": {
    "naumu": {
      "url": "https://naumu.ai/api/mcp"
    }
  }
}

Leave any OAuth client ID and secret fields blank. Naumu registers the client for you automatically during sign-in, using Dynamic Client Registration (DCR).

Other MCP-capable clients that support remote servers follow the same shape: point them at https://naumu.ai/api/mcp and let the browser handle sign-in. Use the front-end origin (naumu.ai), not a backend address - sign-in and consent rely on your Naumu session, which lives on the front-end origin.

You can revoke a connected tool's access at any time in Naumu under Settings > Your agents, in the Active access list.

See Local MCP for the full walkthrough.

Fallback setup: local stdio server with an API key

Use this package when your client cannot do browser OAuth - CI, bots and external agent identities, or a harness that only speaks stdio.

1. Get an API key

1. Open Settings > Your agents in Naumu.
2. Select Create an API key and give it a recognizable name (such as the tool it is for).
3. Copy the key right away. It is shown only once and cannot be retrieved later. Keys start with nmu_.

Use a separate key per tool, so a leak only costs you that one key.

2. Configure your client

You do not install this package globally; your client launches it on demand with npx.

Claude Code

claude mcp add naumu -s user \
  -e NAUMU_API_KEY=nmu_your_key_here \
  -- npx -y -p @naumu/mcp naumu-mcp

Cursor

{
  "mcpServers": {
    "naumu": {
      "command": "npx",
      "args": ["-y", "-p", "@naumu/mcp", "naumu-mcp"],
      "env": {
        "NAUMU_API_KEY": "nmu_your_key_here"
      }
    }
  }
}

Environment variables

Available tools

Both transports expose the same tool surface. Tools marked bot are only registered for bot identity keys (nmubot), which additionally receive a filtered subset based on the identity's permissions.

Spaces and members

Shortened. The full README is on GitHub.