# @knowman/mcp

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

## Tools

| Tool | Purpose |
|---|---|
| `kb_search` | Search saved items in Inbox, Knowledge Base and Archive without bodies; results carry trust. |
| `kb_ask` | Ask a question over the Knowledge Base or one item; returns an answer with citations. |
| `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_memories` | List saved memories such as claims, decisions and playbooks; read-only. |

## 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

Sign in at https://app.knowman.io, create an API key in settings, and set it as `KNOWMAN_API_KEY`. Never commit the key.

## Configuration

Claude Desktop (`claude_desktop_config.json`):

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

Claude Code:

```bash
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.

This server speaks stdio, so it runs on your own machine. It is not a hosted or remote MCP endpoint, so clients that only accept remote servers (for example ChatGPT connectors or claude.ai on the web) cannot use it yet.

## CLI reference

<!-- cli-help:start (generated by "bun run docs:sync"; do not edit by hand) -->
```
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-search
  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.
  --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
  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.
  --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
  Retrieve readable content and metadata for one item from the KnowMan Inbox, Knowledge Base, or Archive.
  --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 from the KnowMan Inbox or Knowledge Base. Every result carries `trust`; 'internal' is the user's own knowledge.
  --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
  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.
  --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.
```
<!-- cli-help:end -->