knowman-mcp

@knowman/mcp

MCP クライアントが KnowMan アカウント内の項目を検索、質問、保存、読み取りできる stdio MCP サーバーです。

ツール

ツール	目的
kb_search	Inbox、Knowledge Base、Archive に保存された項目を本文なしで検索します。結果には信頼度が付与されます。
kb_ask	Knowledge Base または単一の項目について質問し、引用付きの回答を返します。
kb_get_item	1 つの項目のコンテンツとメタデータを読み取ります。
kb_save	URL を Inbox または Knowledge Base に保存します。
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 を実行して確認してください。

上記のパッケージは stdio を使用し、お使いのマシン上で動作します。KnowMan は、リモート MCP サーバーのみを受け付けるクライアント向けに、次に説明するホスト型サーバーも提供しています。

リモート（ホスト型）サーバー

エンドポイント：https://api.knowman.io/mcp（Streamable HTTP、ステートレス、JSON レスポンス、MCP protocol 2025-11-25）。同じ 6 つのツールを公開します。

OAuth でサインインします。 このサーバーは MCP 用 OAuth 2.1 を実装しています。保護対象リソースのメタデータは /.well-known/oauth-protected-resource/mcp、認可サーバーのメタデータは /.well-known/oauth-authorization-server にあり、動的クライアント登録、PKCE（S256）を用いた認可コードフロー、ローテーションするリフレッシュトークンに対応しています。MCP OAuth に対応したクライアントは、エンドポイント URL だけで接続できます。app.knowman.io の同意ページが開くので、サインインして承認すると、クライアントは有効期間 1 時間のアクセストークンとリフレッシュトークンを受け取ります。アクセスは 2 つのスコープに制限されています：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 コネクター、claude.ai カスタムコネクター、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.