knowman-mcp

@knowman/mcp

一个通过标准输入/输出运行的 MCP 服务，让 MCP 客户端可以搜索、提问、保存和读取 KnowMan 账户中的条目。

工具

工具	用途
kb_search	搜索 Inbox、知识库和 Archive 中已保存的条目，不包含正文；结果附带可信度信息。
kb_ask	针对知识库或单个条目提问；返回带引用的答案。
kb_get_item	读取单个条目的内容和元数据。
kb_save	将 URL 保存到 Inbox 或知识库。
kb_recent	列出最近保存的条目。
kb_memories	列出已保存的记忆，例如主张、决策和操作手册；仅供读取。

安装

npx -y @knowman/mcp 会按需运行服务。npm install -g @knowman/mcp 会安装 knowman-mcp 命令。

需要 Node.js 22 或更高版本。

获取密钥

登录 https://app.knowman.io，在设置中创建 API 密钥，并将其设为 KNOWMAN_API_KEY。切勿提交密钥。

配置

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，或项目中的 .cursor/mcp.json）：使用与上方 Claude Desktop 示例相同的 mcpServers JSON。

想通过浏览器登录，而不是粘贴密钥？全局安装软件包（npm install -g @knowman/mcp），然后运行 knowman login。保存的凭据可供 knowman-mcp 共用，因此无需 env 区块。运行 knowman status 进行检查。

上述软件包通过标准输入/输出通信，并在你自己的计算机上运行。KnowMan 还提供托管服务，详见下文，供仅接受远程 MCP 服务的客户端使用。

远程（托管）服务

端点：https://api.knowman.io/mcp（Streamable HTTP、无状态、JSON 响应、MCP protocol 2025-11-25）。该服务提供相同的六种工具。

使用 OAuth 登录。 该服务为 MCP 实现 OAuth 2.1：在 /.well-known/oauth-protected-resource/mcp 提供受保护资源元数据，在 /.well-known/oauth-authorization-server 提供授权服务器元数据，支持动态客户端注册、使用 PKCE（S256）的授权码流程，以及轮换刷新令牌。支持 MCP OAuth 的客户端只需通过端点 URL 连接：客户端会打开 app.knowman.io 上的授权页面，你登录并批准后，客户端便会收到一个有效期为一小时的访问令牌和一个刷新令牌。访问权限仅限两个范围：knowman.read（搜索、读取、提问）和 knowman.write（保存链接）。

也可使用 API 密钥。 在 KnowMan 设置中创建密钥，并以 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>"。

已验证的内容。 官方 MCP TypeScript SDK 客户端已成功通过实时服务完成整个 OAuth 流程（注册、授权、令牌获取、工具调用、刷新）。我们尚未自行测试 ChatGPT connectors、claude.ai custom connectors 或 Cursor；该端点符合这些产品所记录的要求，并允许使用它们采用的重定向 URI。如果其中某个产品无法连接，请提交 issue，并附上产品名称和你看到的错误。

断开应用连接。 打开 KnowMan 设置中的 API 密钥列表，删除名为 OAuth: <app name> 的条目。删除该条目会撤销连接及其刷新令牌。更改密码也会撤销所有已连接的应用。

限制。 API 密钥或 OAuth 令牌不能创建其他 API 密钥。请求会按令牌和 IP 限流。

CLI 参考

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.