Connect KnowMan to Claude Code

Add the KnowMan MCP server

Run the command in the config field. Claude Code documents claude mcp add [options] <name> -- <command> [args...] for adding a stdio server. Everything after -- is passed to the server command. Claude Code MCP documentation.

The command uses npx -y @knowman/mcp to start KnowMan’s standalone stdio server. It requires Node 22 or newer.

Sign in once with knowman login

Instead of putting an API key in the command, run npx -p @knowman/mcp knowman login and complete browser sign-in. The CLI and MCP server share the saved credential, so you can then remove the --env KNOWMAN_API_KEY=km_... part from the server configuration.

You can also create an agent key in the KnowMan web app under Settings > Connections > Connect an AI agent, then pass it with --env KNOWMAN_API_KEY=km_.... Replace the placeholder with your key.

Check the connection

Run claude mcp get knowman to check the connection, or open /mcp in Claude Code. The claude mcp list command reports server health, including ✔ Connected and ✘ Failed to connect. Claude Code MCP documentation.

Use KnowMan’s six tools

kb_search searches saved items by keyword or meaning. kb_ask answers a question with citations. kb_get_item reads one item’s content.

kb_save saves a URL to the Inbox or Knowledge Base with an optional note. kb_recent lists recent items. kb_memories lists saved claims, decisions, and playbooks.

Choose local or project configuration

The CLI command adds a local server by default. Claude Code stores local- and user-scoped entries in ~/.claude.json. Claude Code MCP documentation.

For project scope, add an mcpServers entry to .mcp.json at the project root. Claude Code keeps a project server pending until you approve it by running claude interactively, and workspace trust is required before it reads approvals from repository settings. Claude Code MCP documentation.

If the server does not connect

Check the server health with claude mcp list or check its connection with claude mcp get knowman.

If the stdio server has failed, select Reconnect from its server menu in /mcp. Claude Code MCP documentation.

Use the hosted KnowMan server with Claude Code

KnowMan also runs as a hosted remote MCP server at https://api.knowman.io/mcp, so no local server process is needed. Create an API key in your KnowMan settings, then run: claude mcp add --transport http knowman https://api.knowman.io/mcp --header "Authorization: Bearer <key>". Claude Code connects over HTTP transport and sends the key as an Authorization: Bearer header.

You can also sign in with OAuth. Add the server URL https://api.knowman.io/mcp, sign in, and approve on the KnowMan consent page. The knowman.read scope covers search, read, and ask, and knowman.write covers saving links. Access tokens last one hour and refresh automatically, and you disconnect an app by deleting its "OAuth: <app name>" entry in your KnowMan API-keys list.

The hosted server exposes the same six tools: kb_search, kb_ask, kb_get_item, kb_save, kb_recent, and kb_memories (read-only). Ask Claude to "search my KnowMan for ..." or "save this URL". If you prefer the local option, the open-source client is knowman-mcp on GitHub and runs with npx -y @knowman/mcp.

Set the key and make your first search

Create a key in KnowMan settings and place it in the KNOWMAN_KEY environment variable, for example export KNOWMAN_KEY=<key>. The hosted server at https://api.knowman.io/mcp reads the key from the Authorization header, so the MCP config file for Claude Code takes this shape: {"mcpServers":{"knowman":{"type":"http","url":"https://api.knowman.io/mcp","headers":{"Authorization":"Bearer ${KNOWMAN_KEY}"}}}}

Start with two short prompts. Ask: "Use the knowman kb_recent tool and list the titles it returns". Then ask: "Use the knowman kb_search tool with the query bookmark and list the top results".

Both prompts return a list of saved-item titles from your KnowMan library, so you can see right away what the connection reaches. The same connection gives you six tools in total: kb_search, kb_ask, kb_get_item, kb_save, kb_recent and kb_memories.