peaka-mcp-server

peaka-mcp-server

Model Context Protocol（MCP）は、大規模言語モデル（LLM）と外部システム間のコンテキストを管理するための新しい標準化プロトコルです。

Peaka の text2SQL 機能へのアクセスを提供する、Peaka Model Context Protocol サーバーです。

このサーバーを使用すると、LLM はスキーマを調べ、指定された Peaka プロジェクトで SQL クエリを実行できます。

コンポーネント

リソース

• peaka_sql_query_rule_set
  • Peaka SQL クエリルールセットは、Peaka 用の SQL クエリを記述するためのガイドラインです。
• peaka_artifact_template
  • Peaka のクエリ結果からビジュアルレポート、ダッシュボード、成果物を生成するためのスタイルガイドと HTML テンプレートです。

ツール

プロジェクトを対象とする各ツールは、projectId 引数を受け取ります。MCP クライアントが projectId を把握していない場合は、最初に peaka_list_projects を呼び出し、選択した ID を後続の呼び出しに渡す必要があります。サーバーはプロジェクトの選択状態を保持しません。各呼び出しには、それぞれの projectId が含まれます。

• peaka_list_projects
  • 現在の API キーでアクセス可能なすべてのプロジェクトを一覧表示します。Partner API キーの場合は、すべての組織とワークスペースにまたがるプロジェクトを列挙します。Project API キーの場合は、キーに紐付けられた単一のプロジェクトを返します。
• peaka_query_golden_sqls
  • Peaka のゴールデン SQL ベクトルストアから、質問と SQL のペアを検索します。既存のクエリがユーザーの質問と一致する場合は、そのまま再利用できます。
• peaka_execute_sql_query
  • 指定された SQL クエリを Peaka で実行します。
• peaka_get_project_metadata
  • Peaka プロジェクト内のすべてのカタログ、スキーマ、テーブルのメタデータを1回の呼び出しで取得します。catalogId や schemaName を指定して絞り込むこともできます。
• peaka_list_catalogs
  • Peaka プロジェクトで利用可能なすべてのカタログを一覧表示します。カタログ名、種類、接続情報を返します。
• peaka_list_schemas
  • Peaka プロジェクト内の指定されたカタログで利用可能なすべてのスキーマを一覧表示します。
• peaka_list_tables
  • Peaka プロジェクト内の指定されたカタログとスキーマで利用可能なすべてのテーブルを一覧表示します。
• peaka_list_columns
  • Peaka プロジェクト内の指定されたテーブルのすべてのカラムを一覧表示します。カラム名、データ型、制約を返します。
• peaka_get_relations
  • カタログのテーブル間のリレーション（外部キー）を取得します。正確な JOIN の構築に役立ちます。
• peaka_get_table_statistics
  • テーブルのカラム単位の統計情報を取得します。各カラムの個別値の割合などが含まれます。
• peaka_create_cache
  • Peaka プロジェクト内のテーブルのキャッシュを作成します。テーブルをキャッシュすると、データがローカルに保存され、クエリのパフォーマンスが向上します。
• peaka_create_cache_batch
  • 1回の呼び出しで複数のテーブルのキャッシュを作成します。peaka_create_cache を繰り返し呼び出すよりも推奨されます。
• peaka_get_cache_statuses
  • Peaka プロジェクト内のテーブルのすべてのキャッシュ状態を取得します。現在のキャッシュ状態、実行履歴、進行状況が含まれます。
• peaka_refresh_cache_full
  • 既存のキャッシュの完全更新を開始します。
• peaka_refresh_cache_incremental
  • 既存のキャッシュの増分更新を開始し、新規または変更された行のみを取得します。
• peaka_update_cache
  • 既存のキャッシュの設定（スケジュール）を更新します。呼び出すたびに、両方のスケジュールを完全に置き換えます。
• peaka_delete_cache
  • 既存のキャッシュを削除します。基となるテーブルには影響しません。
• peaka_list_queries
  • Peaka プロジェクトに保存されているすべてのクエリを一覧表示します。クエリ名、SQL の内容、通常のクエリかマテリアライズドクエリかを返します。
• peaka_get_query
  • ID で単一の保存済みクエリを読み取ります。SQL、種類、マテリアライズドクエリの更新スケジュールを含む、クエリオブジェクト全体を返します。
• peaka_execute_query
  • Peaka プロジェクトで、ID を指定して保存済みクエリを実行します。
• peaka_create_query
  • プロジェクトのセマンティックレイヤーに、名前付きの保存済みクエリを作成します。ID を含む作成済みクエリを返します。マテリアライズドクエリでは、オプションの schedule を指定して自動更新の間隔を設定できます。指定できる値は {type: "interval", repeatDuration: "PT6H"}、{type: "cron", cronExpression: "0 0 * * *", timezone: "UTC"}、または無効にする {type: "none"} です。
• peaka_update_query
  • 既存の保存済みクエリの表示名、SQL 本文、および／または自動更新の schedule（interval、cron、または無効にする {type: "none"}）を更新します。マテリアライズドクエリのみが対象です。
• peaka_delete_query
  • Peaka プロジェクトから保存済みクエリを削除します。
• peaka_refresh_materialized_query
  • 保存済みのマテリアライズドクエリの更新を開始します。queryType が MATERIALIZED のクエリ ID を見つけるには、peaka_list_queries を使用してください。
• peaka_get_materialized_query_statuses
  • マテリアライズドクエリの自動更新状態（前回の更新ステータス、前回／次回のスケジュール実行、スケジュール設定）を確認します。単一のクエリを指定する場合は queryId を渡し、すべてを一覧表示する場合は省略します。
• peaka_list_connections
  • Peaka プロジェクト内のすべてのデータソース接続を一覧表示します。各接続の ID、名前、種類が含まれます。
• peaka_get_connection_detail
  • データソース接続の接続固有の設定詳細を取得します。
• peaka_create_semantic_catalog
  • Peaka プロジェクトにセマンティックカタログを作成します。セマンティックカタログは、セマンティックテーブル（クエリ可能なテーブルとして公開された保存済みクエリ）を単一の名前空間にまとめます。
• peaka_create_semantic_table
  • セマンティックカタログ内に、保存済みクエリを基にしたセマンティックテーブルを作成します。catalogId、schemaName、tableName、queryId が必要です。
• peaka_delete_semantic_table
  • セマンティックカタログからセマンティックテーブルを削除します。基となる保存済みクエリには影響しません。
• peaka_refresh_project_metadata
  • 指定されたカタログのプロジェクトメタデータを更新します。時間のかかる処理で、更新を開始して完了まで状態を確認します。
• peaka_get_metadata_refresh_status
  • 指定されたカタログのメタデータ更新ジョブの現在の状態を確認します。

Claude Desktop での使用方法

• 設定ファイル config.json を編集します：
  • macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows の場合：%APPDATA%\Claude\claude_desktop_config.json
• 以下の設定を mcpServers オブジェクトに追加します：

{
  "mcpServers": {
    "peaka": {
      "command": "npx",
      "args": ["-y", "@peaka/mcp-server-peaka@latest"],
      "env": {
        "PEAKA_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

{PEAKA_API_KEY} をプロジェクトの API キーに置き換えてください。API キーの作成方法については Peaka Documentation を確認し、こちらをクリックして詳しい手順をご覧ください。

• Claude Desktop を再起動します

Claude Desktop 拡張機能としてパッケージ化する

このリポジトリには pack スクリプトが含まれています。このスクリプトはサーバーをビルドした後、@anthropic-ai/mcpb の mcpb pack を実行して .mcpb バンドルを生成します。これは、ビルド済みサーバーと manifest.json を含む zip 形式のアーカイブで、Claude Desktop がカスタム MCP 拡張機能として読み込めます。

npm run pack

リポジトリのルートに peaka-mcp-server.mcpb が生成されます。インストールするには、Claude Desktop を開き、Settings → Extensions -> Advanced Settings -> Install Extension -> Select の順に進んで .mcpb ファイルを選択します。プロンプトが表示されたら API キーを入力し、拡張機能を有効にしてください。

環境変数

設定には以下の環境変数を使用できます：

名前	説明	デフォルト値
PEAKA_API_KEY	Peaka サービスとの認証に使用するプロジェクト API キー（stdio モード）。	-
PARTNER_API_BASE_URL	Peaka パートナー API のベース URL	https://partner.peaka.studio/api/v1
OAUTH_ISSUER	認可サーバーの発行者。受信したアクセストークンの iss クレームの検証に使用します（httpStream モードでは必須）。	-
OAUTH_JWKS_URI	アクセストークンの署名検証に使用する認可サーバーの JWKS エンドポイント（httpStream モードでは必須）。	-
OAUTH_REQUIRED_SCOPE	アクセストークンが受け入れられるために必要なスコープ（httpStream モード）。	user_access
OAUTH_RESOURCE	想定されるトークンのオーディエンス（この MCP サーバーのリソース URL）。設定すると、aud が一致しないトークンは拒否されます。認可サーバーで aud がリソースに紐付けられるまでは未設定にしてください。	-

リクエストのタイムアウト（httpStream）

Partner API リクエストのタイムアウトは、デフォルトで 60 秒です。MCP エンドポイント URL に timeoutSeconds クエリパラメーターを指定すると、接続ごとに上書きできます。例：https://mcp.peaka.studio/mcp?timeoutSeconds=120。これにより、再ビルドせずに URL から低速なデプロイやオンプレミス環境の設定を調整できます。

上限は 600 秒（10 分）です。上限を超える値、または値が指定されていない場合や無効な値（数値以外、ゼロ、負の数）の場合は、上限値に丸められるのではなく、デフォルトの 60 秒に戻ります。そのため、timeoutSeconds=60000（ミリ秒のつもりで指定）といった単位の間違いで、リクエストが何時間も開いたままになることはありません。

お問い合わせ

機能のリクエストやバグの報告は、このリポジトリに issue を作成してください。詳しいサポートについては、以下のリソースをご覧ください：

• Peaka Community Discord