@knowman/mcp

A stdio MCP server that lets an MCP client search, ask, save and read items in a KnowMan account.

Tools

Hosted server (remote)

Tool	Purpose
`kb_research`	Retrieve ranked passages and memories across the whole library in one call; the assistant writes the answer.
`kb_get_item`	Read content and metadata for one item.
`kb_recent`	List recently saved items.
`kb_save`	Save a URL to Inbox or Knowledge Base.

Local stdio package

Tool	Purpose
`kb_research`	Retrieve ranked passages and memories across the whole library in one call; the assistant writes the answer. Also served by the local package from 0.3.1.
`kb_get_item`	Read content and metadata for one item.
`kb_save`	Save a URL to Inbox or Knowledge Base.
`kb_recent`	List recently saved items.
`kb_search`	Search saved items without bodies; results carry trust. Deprecated; use `kb_research` on the hosted server.
`kb_ask`	Ask a question over the Knowledge Base or one item; returns an answer with citations. Deprecated; use `kb_research` on the hosted server.
`kb_memories`	List saved memories such as claims, decisions and playbooks; read-only. Deprecated; use `kb_research` on the hosted server.

Install

npx -y @knowman/mcp runs the server on demand. npm install -g @knowman/mcp installs the knowman-mcp command.

Requires Node.js 22 or newer.

Get a key

Configuration

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "knowman": {
      "command": "npx",
      "args": ["-y", "@knowman/mcp"],
      "env": {
        "KNOWMAN_API_KEY": "<your-key>"
      }
    }
  }
}

Claude Code:

claude mcp add knowman --env KNOWMAN_API_KEY=<your-key> -- npx -y @knowman/mcp

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project): use the same mcpServers JSON as the Claude Desktop example above.

Prefer signing in with the browser instead of pasting a key? Install the package globally (npm install -g @knowman/mcp) and run knowman login. The saved credential is shared with knowman-mcp, so the env block is not needed. Run knowman status to check it.

The package runs on your own machine over stdio. KnowMan also runs a hosted server at the endpoint in the next section, for clients that only accept remote MCP servers, such as claude.ai custom connectors.

Remote (hosted) server

Endpoint: https://api.knowman.io/mcp (Streamable HTTP, stateless, JSON responses, MCP protocol 2025-11-25). It exposes four tools: kb_research, kb_get_item, kb_recent and kb_save (see Tools above).

claude.ai. Open Settings, then Connectors, then Add custom connector, and enter https://api.knowman.io/mcp. Sign in with your KnowMan account when the browser opens.

Sign in with OAuth. The server implements OAuth 2.1 for MCP: protected resource metadata at /.well-known/oauth-protected-resource/mcp, authorization server metadata at /.well-known/oauth-authorization-server, dynamic client registration, authorization code with PKCE (S256), and rotating refresh tokens. A client that supports MCP OAuth connects from the endpoint URL alone: it opens a consent page at app.knowman.io, you sign in and approve, and the client receives a one-hour access token plus a refresh token. Access is limited to two scopes: knowman.read (search and read) and knowman.write (save links).

Or use an API key. Create a key in your KnowMan settings and send it as Authorization: Bearer <key>:

{
  "mcpServers": {
    "knowman": {
      "url": "https://api.knowman.io/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}

Claude Code: claude mcp add --transport http knowman https://api.knowman.io/mcp --header "Authorization: Bearer <your-key>".

What has been verified. The official MCP TypeScript SDK client completes the whole OAuth flow against the live server (registration, consent, token, tool calls, refresh). We have not yet tested ChatGPT connectors or Cursor ourselves; the endpoint follows the requirements those products document, and the redirect URIs they use are allowed. If one of them fails to connect, please open an issue with the product and the error you see.

Disconnect an app. Open the API keys list in your KnowMan settings and delete the entry named OAuth: <app name>. Deleting it revokes the connection and its refresh token. Changing your password also revokes every connected app.

Limits. An API key or an OAuth token cannot create other API keys. Requests are rate limited per token and per IP.

CLI reference

KnowMan CLI

Usage:
  knowman <command> [options]

Account:
  login [--web-url <url>] [--api-url <url>] [--label <name>] [--no-browser] [--scopes agent|read]
    Sign in through your browser; the credential is shared with knowman-mcp.
  logout
    Revoke the saved key on the server and remove it.
  status
    Show whether you are signed in (never prints the key).

Global flags:
  --json
  --format <json|text>   json = one compact document; lists become {"results":[...]}
  --api-url <url>
  --api-key <key>
  --help
  --version

Commands (each also works without the kb- prefix, e.g. "save", "search"):
kb-research
  Retrieve ranked evidence across the user's whole library and distilled memories. Default tool for factual, strategic and how-to questions. Returns source passages, not an answer.
  --question <STRING>
  --max_passages <NUMBER> [optional]

kb-search
  Deprecated: use kb_research. Search saved items in the KnowMan Inbox, Knowledge Base, or Archive without returning content bodies; a location filter costs one extra lookup per hit. Every result carries `trust`: 'internal' is the user's OWN knowledge (their pages, documents and designated links) and outranks 'external' saved articles on anything about the user themselves. Returns snippets only; kb_get_item reads the full text.
  --query <STRING>
    Text to search for in KnowMan.
  --limit <NUMBER> [optional]
    Maximum number of search results to return.
  --location <STRING> [optional] (one of: inbox|kb|archive)
    Optional Inbox, Knowledge Base, or Archive location filter.
  --scope <STRING> [optional] (one of: internal|external|all)
    Which knowledge to search: 'internal' (the user's own pages, documents and designated links), 'external' (articles they saved), or 'all'. Defaults to all.

kb-ask
  Deprecated: use kb_research. Ask a question over the whole Knowledge Base (or a single item when itemId is given); returns an answer plus citations whose itemId resolves via kb_get_item. Answers specific questions with citations; may abstain on broad questions: then use kb_memories, kb_search and kb_get_item.
  --question <STRING>
    Question to ask over the KnowMan Knowledge Base.
  --item-id <STRING> [optional]
    Optional item id restricting the question.
  --project-id <STRING> [optional]
    Optional project id restricting the question.

kb-get-item
  Read the full text of one saved item by id when research evidence needs more context.
  --id <STRING>
    KnowMan item id to retrieve.

kb-save
  Save a URL to the KnowMan Inbox or directly to the Knowledge Base. Pass trust:'internal' when the link is the user's own knowledge (their company docs, their own writing) rather than an outside article.
  --url <STRING>
    URL to save into KnowMan.
  --location <STRING> [optional] (one of: inbox|kb)
    Save into the Inbox or directly into the Knowledge Base.
  --note <STRING> [optional]
    Optional note to attach to the saved item.
  --trust <STRING> [optional] (one of: internal|external)
    Mark the saved link as the user's own knowledge ('internal' — their company docs, their own posts) rather than an outside article ('external', the default).

kb-recent
  List recently saved items. Use only when the user asks about recent saves.
  --limit <NUMBER> [optional]
    Maximum number of recent items to return.
  --location <STRING> [optional] (one of: inbox|kb)
    Optional Inbox or Knowledge Base location filter.
  --scope <STRING> [optional] (one of: internal|external|all)
    Which knowledge to list: 'internal', 'external', or 'all' (default).
  --source-type <ARRAY> [optional]
    Optional source type filter: manual, extension, rss, newsletter, inbox, or import. Array or comma-separated string. Use sourceType:['manual','extension'] to return only the user's own saves (manual and extension saves). Defaults to all types.

kb-memories
  Deprecated: use kb_research. List saved memories (claims, decisions, playbooks) from the Knowledge Base; use kind 'playbook' to find step-by-step processes the user has taught KnowMan. Read-only. Best first stop for process, strategy and how-to questions (kind 'playbook').
  --project <STRING> [optional]
    Optional project id as a UUID; project name lookup is unavailable.
  --kind <STRING> [optional] (one of: claim|decision|playbook)
    Optional memory kind: claim, decision, or playbook.
  --query <STRING> [optional]
    Optional case-insensitive title and body substring filter.
  --limit <NUMBER> [optional]
    Maximum number of memories to return.

knowman-mcp

Documentation