Knowi

Knowi MCP Server

Claude Code、Claude Desktop、Cursor、またはその他の MCP 対応 AI クライアントを Knowi に接続できます。AI アシスタントから自然言語で直接、データのクエリ、ダッシュボードの作成、レポートの管理などを行えます。

MCP サーバーは Knowi アプリケーションに組み込まれています。別途インストールする必要はありません。

クイックスタート

1. MCP トークンを生成する

1. Knowi にログインします
2. 設定 → AI 設定 に移動します
3. MCP Token で有効期限を選択し、Generate Token をクリックします
4. トークンをコピーします。表示されるのは一度だけです

2. Claude Code に接続する

claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

knowi.com アカウントの場合：

claude mcp add knowi https://www.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

3. Claude Desktop に接続する

設定ファイルを編集します。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "knowi": {
      "type": "streamable-http",
      "url": "https://your-instance.knowi.com/api/2.0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

保存後、Claude Desktop を再起動します。

4. 確認する

"What Knowi tools are available?"

knowi_do、knowi_ask、knowi_search、knowi_list_dashboards などのツールが表示されます。

---

利用可能なツール

AI 搭載ツール

Knowi の AI オーケストレーターを使用して指示を解釈し、操作を連鎖させる自然言語ツールです。

ツール	説明
knowi_do	自然言語で任意の Knowi 操作を実行します
knowi_ask	データに関する質問をします。データセットを見つけ、クエリを生成し、結果を返します
knowi_search	すべてのダッシュボード、ウィジェット、データセット、レポートを検索します

決定論的ツール

予測可能な動作をする、直接的で高速な操作です。

ツール	説明
knowi_list_dashboards	アクセス可能なすべてのダッシュボードを一覧表示します
knowi_get_data	ウィジェットまたはデータセットからデータ行を取得します
knowi_push_data	データ行をデータセットに送信します（存在しない場合は作成します）
knowi_get_details	任意のアセットのメタデータをすべて取得します
knowi_find_widget	名前でウィジェットを検索します
knowi_create_datasource	新しいデータソース接続を作成します
knowi_create_query	データソースに対するクエリを作成して実行します
knowi_create_widget	新しいチャートまたは可視化を作成します
knowi_update_widget	既存のウィジェットを更新します
knowi_create_report	スケジュールされたレポートを作成します
knowi_create_alert	データアラートを作成します
knowi_list_alerts	設定済みのアラートを一覧表示します
knowi_test_alert	アラートをテストします
knowi_update_alert	アラートを更新します
knowi_run	クエリまたはレポートの実行を開始します
knowi_export_pdf	ダッシュボードまたはウィジェットを PDF としてエクスポートします
knowi_export_csv	データを CSV としてエクスポートします
knowi_get_embed_url	埋め込み可能な共有 URL を生成します
knowi_get_insights	ウィジェットに関する AI 生成のインサイトを取得します
knowi_layout_dashboard	ダッシュボード上のウィジェットを配置します
knowi_import_file	ファイル（CSV、Excel）をデータセットとしてインポートします
knowi_ingest_document	AI による質問応答のためにドキュメントを取り込みます
knowi_ask_document	取り込んだドキュメントについて質問します
knowi_extract_document_data	ドキュメントから構造化データを抽出します
knowi_list_documents	取り込んだドキュメントを一覧表示します
knowi_delete_document	取り込んだドキュメントを削除します
knowi_delete	アセットを削除します（明示的な確認が必要です）

---

使用例

"Show me my Knowi dashboards"

"Ask Knowi: what were our top customers by revenue last month?"

"Create a sales dashboard with revenue trends and top products"

"Search Knowi for dashboards related to customer analytics"

"Get the data from the Monthly Revenue widget"

"Export the Executive Summary dashboard to PDF"

"Push these sales records to a Knowi dataset called 'Daily Sales'"

"Set up a daily email report for the executive dashboard"

---

トークン管理

トークンをローテーションする場合：

1. 設定 → AI 設定 → MCP Token に移動します
2. Revoke Token をクリックします
3. 新しいトークンを生成し、設定を更新します。

claude mcp remove knowi
claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_NEW_TOKEN"

ユーザーごとにトークンは 1 つです。 新しいトークンを生成すると、以前のトークンは自動的に無効になります。

---

API リファレンス

MCP サーバーは、ストリーミング可能な HTTP（MCP クライアント向け）と REST エンドポイント（プログラムから直接利用する場合）の両方を公開します。

ヘルスチェック

curl https://your-instance.knowi.com/api/2.0/mcp/health

{
  "status": "healthy",
  "toolCount": 28,
  "tools": ["knowi_do", "knowi_ask", "knowi_search", "..."],
  "activeSessions": 0
}

ツール一覧

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.knowi.com/api/2.0/mcp/tools

ツールの呼び出し（REST）

curl -X POST https://your-instance.knowi.com/api/2.0/mcp/tools/call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowi_list_dashboards",
    "arguments": {}
  }'

ストリーミング可能な HTTP（JSON-RPC）

すべての MCP クライアント操作では、標準の JSON-RPC を使用して POST /api/2.0/mcp にリクエストします。

# Initialize
curl -X POST https://your-instance.knowi.com/api/2.0/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

レスポンスには、後続のリクエストで使用する Mcp-Session-Id ヘッダーが含まれます。

---

セキュリティ

• スコープを限定した認証情報：MCP トークンは MCP エンドポイントにのみアクセスできます。より広範な Management API に対して使用することはできません。
• すべてのリクエストで認可を実施：すべてのツールは、実行前に認証済みユーザーが要求されたリソースへのアクセス権を持っていることを確認します。
• プロンプトインジェクション対策：AI を活用したツールは、既知のインジェクションパターンが指示に含まれていないかを検査し、AI モデルに届く前に拒否します。
• 破壊的な操作への対策：knowi_do は削除／ドロップ／パージの指示をブロックします。削除には、必須パラメーター confirm: true を指定した明示的な knowi_delete ツールが必要です。
• データの切り詰め：knowi_get_data と knowi_ask は、デフォルトで最大 100 行を返します。
• セッションのセキュリティ：Streamable HTTP セッションは認証済みユーザーに紐付けられます。セッション ID だけではアクセス権は付与されません。

データフロー

Claude が Knowi MCP ツールを呼び出すと、ツールの応答（データ行、メタデータ、インサイト）が Claude に返され、Anthropic のインフラストラクチャ上で処理されます。これは MCP の仕組み上避けられません。クライアントは結果を受け取って、それに基づいて処理を行う必要があります。

データの分離を最大限に高めるには、MCP の代わりに Knowi の製品内 AI エージェントを使用してください。

---

トラブルシューティング

Claude にツールが表示されない場合：

• Claude Code／Claude Desktop を完全に再起動してください
• サーバーに到達できることを確認してください：curl https://your-instance.knowi.com/api/2.0/mcp/health
• トークンが有効であることを確認してください：curl -H "Authorization: Bearer TOKEN" https://your-instance.knowi.com/api/2.0/mcp/tools

claude mcp list で「Failed to connect」と表示される場合：

• --transport http を使用したことを確認してください（Streamable HTTP に必須です）
• トランスポートが正しく設定されていない場合は、サーバーを削除してから再追加してください

401 エラー：

• トークンの有効期限が切れているか、取り消されている可能性があります。Settings → AI Settings から新しいトークンを生成し、設定を更新してください。

ツール呼び出しでアクセス拒否が返される場合：

• 設定したトークンのユーザーには、要求されたリソースへのアクセス権がありません。
• 本番環境で使用する場合は、必要最小限の権限を持つ専用の Knowi ユーザーを作成してください。

---

要件

• AI Agents が有効になっている Knowi アカウント（Settings → AI Settings）
• Claude Code CLI、Claude Desktop、または MCP 対応クライアント

---

ドキュメント

• MCP サーバーリファレンス — API リファレンス、すべてのツールスキーマ、セキュリティモデル
• Claude Code セットアップガイド — 手順を追ったセットアップ方法
• Knowi ドキュメント — 製品ドキュメント全般

---

サポート

• ドキュメント： knowi.com/docs
• サポート： support.knowi.com
• このリポジトリに関する問題： GitHub issue を作成してください