Naumu

ai.naumuPublished by naumu.aiOfficial publisherv0.19.1Updated Nov 7, 2026

Search, extend, and act on your team's Naumu knowledge graph: notes, threads, and nodes.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowKnowledge & MemoryCommunication & Collaboration

Overview

AI-generated overview

Connects an assistant to a team's Naumu knowledge graph so it can search, extend, and act on notes, threads, and nodes.

What you can do
  • List spaces, members and identity, and manage space admission and whitelisting
  • Read and audit a space's schema, adding node types, attributes and connections
  • Search, filter and read nodes, inspect connections and dense hubs, or ask @Naumu a grounded question
  • Create, update, delete and reparent nodes and edges, and delegate tasks to @Naumu
  • Work with threads and topics: list, read, post messages, react, and create threads or topics
  • Create, read and edit notes section by section, and handle attachments
When to use it
Useful when a team keeps its knowledge in Naumu and wants an AI agent to look things up, keep the graph and notes up to date, or take part in threads from Claude Code, Cursor or another MCP client. The local package suits CI jobs, bot identities and stdio-only clients that cannot do browser sign-in.
Requirements
Either the remote endpoint at naumu.ai/api/mcp with browser OAuth sign-in (recommended), or the npm package @naumu/mcp run with npx over stdio. The local path needs a Naumu account and an API key in NAUMU_API_KEY; NAUMU_API_URL and NAUMU_IDENTITY_ID are optional. Network access to Naumu is required.
Before you install
The local path requires an API key in NAUMU_API_KEY, shown only once at creation; use a separate key per tool and revoke access under Settings > Your agents. Many tools write or delete data, including destructive node, edge and note removals and schema replacement. Bot keys get a permission-filtered subset of tools. Attachments are uploaded via presigned URLs.

Installation

In SourceWeft

  1. Open Naumu in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/ai.naumu%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

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

README

@naumu/mcp

[npm]

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

bash
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

json
{  "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
bash
claude mcp add naumu -s user \  -e NAUMU_API_KEY=nmu_your_key_here \  -- npx -y -p @naumu/mcp naumu-mcp
Cursor
json
{  "mcpServers": {    "naumu": {      "command": "npx",      "args": ["-y", "-p", "@naumu/mcp", "naumu-mcp"],      "env": {        "NAUMU_API_KEY": "nmu_your_key_here"      }    }  }}

Environment variables

VariableRequiredDefaultDescription
NAUMU_API_KEYYes-Your API key (starts with nmu_)
NAUMU_API_URLNohttps://naumu.aiNaumu API base URL. You do not need to set this

Available tools

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

Spaces and members

ToolDescription
naumu_list_graphsList every space (graph) the key can access, with ids, names, and roles
naumu_create_graphCreate a new, empty space owned by the authenticated user
naumu_list_membersList a space's members with their roles
naumu_whoamiReturn who the calling key is (user, or bot identity with its graph and allowed tools)

Schema

ToolDescription
naumu_get_schemaGet a space's schema (node types, attributes, connections)
naumu_update_schemaReplace the schema with a full new definition
naumu_add_node_typeAdd one node type without resending the whole schema
naumu_add_connectionAdd one connection from an existing node type to another
naumu_add_attributeAdd or extend an attribute on an existing node type
naumu_list_schema_violationsAudit a space against its schema and report violations

Reading the graph

ToolDescription
naumu_searchHybrid (meaning plus text) search over graph nodes
naumu_filterFilter nodes by type and attributes, with deterministic and complete results
naumu_get_nodeGet one node with its properties, edges, notes, threads, and generated context
naumu_list_node_connectionsList a single node's connections
naumu_list_dense_nodesFind over-connected hub nodes by child count
naumu_askAsk @Naumu a question and get a synthesised, node-grounded answer with sources and confidence

Writing to the graph

ToolDescription
naumu_add_nodeCreate 1-25 nodes in one call
naumu_update_nodeOverwrite properties of an existing node
naumu_remove_nodeDelete a node and all of its connections (destructive)
naumu_add_edgeCreate 1-25 edges between existing nodes
naumu_remove_edgeDelete one edge identified by (source, target, label)
naumu_remove_edges_bulkDelete 1-100 edges in one atomic call
naumu_reparentAtomically swap a node's parent edge
naumu_batch_reparentReparent 1-25 nodes onto a shared new parent
naumu_delegateHand @Naumu a task to carry out asynchronously; returns a threadId to poll

Threads and topics

ToolDescription
naumu_list_threadsList threads by last activity, with an isParticipant flag
naumu_get_threadFetch one thread plus its human and bot participant rosters
naumu_read_threadRead a thread's messages; each carries processing or complete status
naumu_post_messagePost a markdown message in a thread you participate in
naumu_create_threadbot Start a new conversation, attach participants, post a first message, optionally file into topics
naumu_add_reactionAdd an emoji reaction to a message (idempotent)
naumu_remove_reactionRemove your own reaction from a message
naumu_typingShow or hide your "is typing" indicator in a thread
naumu_list_topicsList a space's topics (filing destinations) for use in topicIds
naumu_create_topicCreate a topic; admin-only, name must be a lowercase slug

Notes

ToolDescription
naumu_create_noteCreate a note, optionally with its full markdown body in the same call
naumu_note_readRead a note's current markdown plus the nodes it is tied to
naumu_note_appendAppend markdown blocks to the end of a note
naumu_note_insertInsert markdown immediately after a named heading
naumu_note_replace_sectionReplace the body under a named heading
naumu_note_delete_sectionDelete a heading and its body (destructive)
naumu_note_replaceReplace an entire note's content (destructive)
naumu_note_find_replaceLiteral find and replace within a note

Attachments

ToolDescription
naumu_request_attachment_uploadGet a presigned S3 URL to upload a file, then reference it via attachmentIds
naumu_get_attachmentRead a chat attachment by attachmentId
naumu_persist_canvas_attachmentPromote a canvas-bound pending attachment to a persisted one

Space admission

ToolDescription
naumu_admission_statusShow who can auto-join a space and who is waiting for approval
naumu_whitelist_membersWhitelist emails so those people auto-join on sign-in
naumu_resolve_admissionJoin (or request to join) the space a repo's .naumu file references
naumu_resolve_join_requestApprove or deny a pending join request

ChatGPT compatibility

The OpenAI MCP surface requires tools literally named search and fetch. These wrap cross-space search and node reads in the response shapes that client expects.

ToolDescription
searchSearch across every accessible space; returns { results: [{ id, title, url }] }
fetchFetch a node returned by search; returns { id, title, text, url }

Troubleshooting

When the stdio server is misconfigured it exits before the MCP handshake, and most clients simply show no server at all, with no error. Run the built-in self-check to find out why:

bash
npx -y -p @naumu/mcp naumu-mcp doctor

It checks, in order, that NAUMU_API_KEY is set (the key itself is never printed), that the API is reachable and accepts the key, and that this build matches the latest published version. It prints one line per check plus a verdict, and exits non-zero if anything failed:

naumu-mcp doctor (v0.11.1, API https://naumu.ai)
[fail] API key: NAUMU_API_KEY is missing from the environment[warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify[ok]   Version: running 0.11.1 (npm latest)
Verdict: 1 check failed - the MCP server will not work until this is fixed.Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)

Run it with the same environment your MCP client uses, otherwise the key check reports on your shell rather than on the client's configuration.

License

MIT

Source: README.md at commit 5a56158

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

7
  1. v0.19.1LatestOct 9, 2026
  2. v0.19.0Oct 8, 2026
  3. v0.18.3Oct 2, 2026
  4. v0.18.2Sep 30, 2026
  5. v0.18.1Sep 24, 2026
  6. v0.18.0Sep 21, 2026
  7. v0.17.0Sep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts