Altinity Mcp

Altinity MCP Server

ClickHouse® データベースとやり取りするためのツールを提供する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、AI アシスタントやその他の MCP クライアントは、標準化されたプロトコルを介して ClickHouse® データベースに対するクエリ、分析、操作を行えます。

特長

• 複数のトランスポートオプション：STDIO、HTTP、Server-Sent Events（SSE）トランスポートをサポートします
• ステートレス MCP プロトコル：HTTP トランスポートはステートレス MCP プロトコル（仕様リビジョン 2026-07-28）を提供します。セッションアフィニティは不要で、ラウンドロビン方式のロードバランサーの背後でも安全に実行できます。古いクライアントでは、2025-11-25 以前のバージョンに透過的にネゴシエーションされます
• OAuth 2.0 認証：任意の OIDC プロバイダーに対する MCP クライアントの OAuth フローを仲介します。ClickHouse の Bearer 認証と Basic 認証を自動検出します（OAuth 2.0 のドキュメントを参照）
• JWE 認証：データベースへの安全なアクセスを実現する、暗号化を用いたオプションの JWE ベース認証
• TLS サポート：ClickHouse® 接続と MCP サーバーエンドポイントの両方で、完全な TLS 暗号化をサポートします
• 包括的なツール：テーブルの一覧表示、スキーマの説明、クエリの実行を行う組み込みツール
• 動的ツール：ClickHouse® のビューやテーブルから MCP ツールを自動生成します（ツールのドキュメントを参照）
• リソーステンプレート：データベーススキーマやテーブル情報を動的に検出します
• クエリプロンプト：AI を活用したクエリの作成と最適化のためのプロンプト
• 構成管理：ファイル、環境変数、CLI フラグによる柔軟な構成
• ホットリロード：サーバーを再起動せずに構成を動的に再読み込みします

目次

• クイックスタート
• 統合ガイド
• インストールとデプロイ
• 構成
• 利用可能なツール
• 利用可能なリソース
• 利用可能なプロンプト
• OpenAI GPTs との統合
• OAuth 2.0 認証
• JWE 認証
• TLS 構成
• 開発とテスト
• CLI リファレンス
• 貢献
• ライセンス
• サポート

クイックスタート

STDIO トランスポートを使用する（デフォルト）

# Basic usage with default settings
./altinity-mcp --clickhouse-host localhost --clickhouse-port 8123

# With custom database and credentials
./altinity-mcp \
  --clickhouse-host clickhouse.example.com \
  --clickhouse-port 9000 \
  --clickhouse-protocol tcp \
  --clickhouse-database analytics \
  --clickhouse-username reader \
  --clickhouse-password secret123 \
  --clickhouse-limit 5000

OpenAPI と HTTP トランスポートを使用する

./altinity-mcp \
  --transport http \
  --address 0.0.0.0 \
  --port 8080 \
  --clickhouse-host localhost \
  --openapi http

JWE 認証と OpenAPI を使用した SSE トランスポート

./altinity-mcp \
  --transport sse \
  --port 8080 \
  --allow-jwe-auth \
  --jwe-secret-key "your-jwe-encryption-secret" \
  --jwt-secret-key "your-jwt-signing-secret" \
  --clickhouse-host localhost \
  --openapi http

統合ガイド

Altinity MCP をさまざまな AI ツールやプラットフォームに統合する詳しい手順については、統合ガイドをご覧ください。

インストールとデプロイ

Docker を使用する

docker run -it --rm ghcr.io/altinity/altinity-mcp:latest --clickhouse-host clickhouse

Helm を使用した Kubernetes

OCI Helm レジストリから（推奨）

# Install from OCI registry
helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
  --set config.clickhouse.host=clickhouse.example.com \
  --set config.clickhouse.database=default \
  --set config.clickhouse.limit=5000

ローカルの Helm チャートから

git clone https://github.com/Altinity/altinity-mcp
cd altinity-mcp
helm install altinity-mcp ./helm/altinity-mcp \
  --set config.clickhouse.host=clickhouse-service \
  --set config.clickhouse.database=analytics \
  --set config.server.transport=http \
  --set config.server.port=8080

タグ公開済みの GHCR イメージから

helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
  --set image.tag=<tag-or-sha-tag> \
  --set config.clickhouse.host=clickhouse.example.com \
  --set config.clickhouse.database=default

Helm チャートの構成オプションの詳細については、Helm チャートの READMEをご覧ください。

Docker Compose

version: '3.8'
services:
  altinity-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      - CLICKHOUSE_HOST=clickhouse
      - MCP_TRANSPORT=http
      - MCP_PORT=8080
    depends_on:
      - clickhouse
    entrypoint: ["/bin/sh", "-c", "/bin/altinity-mcp"]
  
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    ports:
      - "8123:8123"

golang をインストールして使用する

go install github.com/altinity/altinity-mcp/cmd/altinity-mcp@latest
$(go env GOPATH)/bin/altinity-mcp --help

ソースから

git clone https://github.com/altinity/altinity-mcp.git
cd altinity-mcp
go build -o altinity-mcp ./cmd/altinity-mcp

構成

構成ファイル

YAML または JSON の構成ファイルを作成します。

# config.yaml
clickhouse:
  host: "localhost"
  # Optional TCP destination override. The logical host above remains the
  # HTTP Host header and TLS SNI/certificate verification name.
  connect_host: ""
  port: 8123
  database: "default"
  username: "default"
  password: ""
  protocol: "http"
  read_only: false
  max_execution_time: 600
  tls:
    enabled: false
    ca_cert: ""
    client_cert: ""
    client_key: ""
    insecure_skip_verify: false

server:
  transport: "stdio"
  address: "0.0.0.0"
  port: 8080
  tls:
    enabled: false
    cert_file: ""
    key_file: ""
    ca_cert: ""
  jwt:
    enabled: false
    secret_key: ""
  openapi:
    enabled: false
    tls: false
  metrics:
    enabled: false
  dynamic_tools:
    - regexp: "mydb\\..*"
      prefix: "db_"
    - name: "get_user_data"
      regexp: "users\\.user_info_view"

logging:
  level: "info"

connect_host が設定されている場合、ClickHouse の HTTP 接続では HTTP_PROXY および HTTPS_PROXY よりも優先されるため、設定したアドレスが常に TCP の接続先になります。 connect_host が空の場合、環境変数によるプロキシの動作は変わりません。

注：動的ツールの構成について詳しくは、ツールのドキュメントをご覧ください。

構成ファイルを使用します。

./altinity-mcp --config config.yaml

環境変数

pkg/config/config.go 内で flag: タグが付いたすべての設定フィールドは、CLI フラグまたは環境変数で設定できます。CLI フラグ名と環境変数名は、各フィールドの flag: タグと env: タグに記載されています。altinity-mcp --help で利用可能なすべての設定を確認できます。

一般的な例：

export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_DATABASE=analytics
export CLICKHOUSE_LIMIT=5000
export MCP_TRANSPORT=http
export MCP_PORT=8080
export MCP_METRICS_ENABLED=true
export LOG_LEVEL=debug

# OAuth — env-var injection lets operators pull secrets from a Kubernetes
# Secret via `valueFrom.secretKeyRef` instead of committing them to YAML.
export MCP_OAUTH_ENABLED=true
export MCP_OAUTH_BROKER=true
export MCP_OAUTH_ISSUER=https://accounts.example.com
export MCP_OAUTH_SIGNING_SECRET=...

./altinity-mcp

このパターンに従わない特殊なフラグ：--config（設定ファイルのパス）、--config-reload-time、--openapi（1 つのフラグで 2 つの構造体フィールドを設定）。altinity-mcp --help を参照してください。

Prometheus メトリクス

HTTP および SSE トランスポート（JWE モードとマルチクラスター・モードを含む）では、 server.metrics.enabled、MCP_METRICS_ENABLED、または --metrics-enabled が true の場合に /metrics が公開されます。メトリクスはデフォルトで無効です。無効な場合、サーバーは完全に何も行わず、/metrics ルート、リクエストミドルウェア、クエリの計測、コレクターの登録は行われません。

server.metrics.enabled の変更は再起動が必要です。設定の再読み込みで値が変更されると警告がログに記録され、HTTP サーバーの起動時にルートとミドルウェアが設定されるため、実行中の値が維持されます。

エンドポイントでは、標準の Go ランタイムおよびプロセスのコレクターに加えて、以下のメトリクスが提供されます。

メトリクス	種類	ラベル	意味
altinity_mcp_http_requests_total	カウンター	route、method、status	登録済みルートパターン、正規化されたメソッド（GET、POST、…、other）、ステータスクラス（2xx、4xx、…）ごとのリクエスト数
altinity_mcp_http_request_duration_seconds	ヒストグラム	route	ハンドラーのエンドツーエンドのレイテンシ
altinity_mcp_clickhouse_queries_total	カウンター	kind、outcome	select／execute および ok／error ごとの ClickHouse クエリ数
altinity_mcp_clickhouse_query_duration_seconds	ヒストグラム	kind	ClickHouse の往復レイテンシ
altinity_mcp_clickhouse_query_rows	ヒストグラム	kind	成功したクエリが返す行数
altinity_mcp_clickhouse_query_bytes	ヒストグラム	kind	成功したクエリが返す概算バイト数
altinity_mcp_blocked_clause_rejections_total	カウンター	clause	blocked_query_clauses によって拒否されたクエリ数
altinity_mcp_clickhouse_up	ゲージ		最後の /health レディネス確認の結果（1／0）。静的な認証情報が存在しない JWE／OAuth モードでは NaN
altinity_mcp_catalog_cache_*	ゲージ／カウンター		マルチクラスターのカタログキャッシュの動作状況（マルチクラスター・モードのみ）

すべてのラベルは固定された値の集合から選ばれます。ルートラベルには生の URL ではなく登録済みパターンが使われるため、JWE トークンは含まれません。標準セット以外のメソッドは other にまとめられ、ステータスコードはステータスクラスにまとめられます。

/metrics エンドポイントには認証がありません。/health と同様に、ネットワークアクセスを制限してください。

Helm チャートでは、エンドポイントの設定に metrics.enabled を使用します。既存の HTTP サービスポートをスクレイピングする Prometheus Operator の ServiceMonitor を作成するには、metrics.serviceMonitor.enabled も設定してください。 config.server.tls.enabled が true の場合、ServiceMonitor は自動的に https 経由でスクレイピングします。Prometheus がサーバー証明書を信頼しない場合は、metrics.serviceMonitor.tlsConfig を指定してください。

利用可能なツール

execute_query

オプションで結果の件数を制限し、ClickHouse® に対して SQL クエリを実行します。

MCP ツールの安全性アノテーション：

• サーバーが --read-only を指定して実行されている場合、execute_query は読み取り専用として公開されます。
• それ以外の場合、execute_query は破壊的な操作を行う可能性があるものとしてマークされます。

パラメーター：

• query（必須）：実行する SQL クエリ
• limit（任意）：返す行数の上限（デフォルト：サーバーで設定された上限、最大：10,000）

動的ツール

ClickHouse ビューから生成される動的ツールは、明示的な安全性のヒントを付けた読み取り専用の MCP ツールとして常に公開されます。

ビューの COMMENT には、次のいずれかを指定できます。

• 文字列による説明。
• 最上位に title、description、annotations を含む、厳密な JSON オブジェクト。

例とサポートされるメタデータについては、ツールドキュメントを参照してください。

利用可能なリソース

clickhouse://schema

ClickHouse® データベースのスキーマ情報全体を JSON 形式で提供します。

clickhouse://table/{database}/{table}

スキーマ、サンプルデータ、統計情報など、特定のテーブルの詳細情報を提供します。

利用可能なプロンプト

現在、利用可能なプロンプトはありません

OpenAI GPTs との統合

Altinity MCP サーバーは、OpenAPI 互換エンドポイントを通じて OpenAI GPTs とシームレスに統合できます。これらのエンドポイントを使用すると、GPT アシスタントが ClickHouse® データベースを直接操作できます。

OpenAI の MCP／ツール関連リファレンス：

• Apps SDK リファレンス
• ツールの定義
• MCP サーバーの構築
• MCP の概念／サーバーのドキュメント

認証

• JWE を使用する場合：JWE トークンを次のいずれかに追加します。
  1. パスパラメーター：/{jwe_token}/openapi/...
  2. Authorization ヘッダー：Bearer {token}（代替）
  3. x-altinity-mcp-key ヘッダー（代替）
• OAuth を使用する場合：Authorization: Bearer {token} を送信します。
• 両方を使用する場合：自己完結型の JWE が優先されます。それ以外の場合は、OAuth から認証情報が提供されます。
• 両方を無効にする場合：サーバーで設定された ClickHouse 認証情報を使用します。

いずれかのモードが有効な場合、正確な /openapi スキーマルートにも認証が必要です。動的 HTTP／SSE ツールと OpenAPI スキーマでは、呼び出し元の有効な認証情報ごとに分離されたカタログが使用されます。認証時にサーバーの認証情報がフォールバックとして使われることはありません。有効な設定が変更されるとカタログの世代がリセットされ、既存の SSE クライアントは再接続が必要になります。変更のない再読み込みポーリングではセッションが維持されます。動的ディスカバリーを参照してください。

利用可能なアクション

1. 読み取り専用 SQL クエリの実行

パス：/openapi/execute_query
パラメーター：

• jwe_token（パスパラメーター）：JWE 認証トークン
• query（クエリパラメーター）：実行する読み取り専用 SQL クエリ（必須）。clickhouse.read_only: false の場合でも、書き込みは常に拒否されます。
• limit（クエリパラメーター）：返す最大行数（任意、デフォルトは 1000、最大 10000）

OpenAPI パスの例：

GET /{jwe_token}/openapi/execute_query?query=SELECT%20*%20FROM%20table&limit=500

clickhouse.max_query_length は、クエリのバイト数と動的ツールの JSON 本文のサイズに上限を設定します（デフォルトは 10 MiB、負の値を指定すると上限は無効になります）。上限を超える入力は、ClickHouse に接続する前に HTTP 413 を返します。OpenAPI では write_query は公開されません。

GPTs の設定例

{
  "openapi": "3.1.0",
  "info": {
    "title": "ClickHouse® SQL Interface",
    "version": "1.0.0"
  },
  "servers": [
    {"url": "https://your-server:8080/{token}"}
  ],
  "paths": {
    "/{jwe_token}/openapi/execute_query": {
      "get": {
        "operationId": "execute_query",
        "parameters": [
          {
            "name": "jwe_token",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          },
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {"type": "string"}
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {"type": "integer"}
          }
        ]
      }
    }
  }
}

注：Altinity Cloud のデプロイでは、組織固有のトークンと、提供されたエンドポイント URL を使用してください。

認証と認可

トークンに空でない host と username のクレームが含まれている場合、JWE が優先されます。 完全な JWE では、OAuth による上書きを使用せず、JWE 自身の接続フィールドが使われます。不完全な JWE クレームは OAuth にフォールスルーし、OAuth に設定されたエンドポイントを変更できません。 無効な暗号化トークンは拒否されます。

OAuth 2.0 認可

MCP サーバーは、OAuth 2.0／OpenID Connect 認証をサポートしています。Bearer トークンは ClickHouse に提示するか、ローカルで検証できます。これにより、MCP クライアントは Identity Provider（Keycloak、Azure AD、Google、AWS Cognito）を介して認証し、token_processors によるトークンベースの ClickHouse 認証を利用できます。

OAuth ヘッダー、クエリ設定、ロールの有効化は、リクエストごと、クラスターごとに分離されています。呼び出し元の bearer token を転送しても、設定済みの ClickHouse ヘッダーや後続のリクエストは変更されません。

詳しい設定手順、プロバイダー固有のガイド、ClickHouse の設定については、OAuth 2.0 認可のドキュメントを参照してください。

JWE 認証

JWE 認証が有効な場合、サーバーは AES Key Wrap（A256KW）および AES-GCM（A256GCM）を使用して暗号化されたトークンを要求します。これらのトークンには、ClickHouse® の接続パラメーターが含まれます。

{
  "host": "clickhouse.example.com",
  "port": 8123,
  "database": "analytics",
  "username": "user123",
  "password": "secret",
  "protocol": "http",
  "secure": "false"
}

JWE トークンは自己完結型です。host と username は必須です。password が存在しない場合、または空の場合は、空のままになります。サーバーのエンドポイント、認証情報、ヘッダー、ロール、TLS 設定によって、不足しているクレームが補われることはありません。引き継がれるのは、運用上のプロトコル設定とクエリ設定のみです。ポートが省略された場合、HTTP では 8123、TCP では 9000 がデフォルトになります。サーバーの接続デフォルト値に依存していた古いトークンは再生成してください。

空でないトークンの TLS ファイルパスを使用するには、server.jwe.tls_material_dir（--jwe-tls-material-dir、MCP_JWE_TLS_MATERIAL_DIR）が必要です。パスはシンボリックリンク解決後も、このオペレーター管理ディレクトリ内に収まっている必要があります。JWE 移行と TLS 許可リストのガイドを参照してください。

HTTP/SSE の /jwe-token-generator エンドポイントは、デフォルトで無効になっています。管理者による発行を有効にするには、server.jwe.token_generator.enabled: true を設定し、32 バイト以上の MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN を注入してください。各リクエストでは、Authorization: Bearer トークンとしてこのシークレットを指定する必要があります。このエンドポイントは信頼できる管理ネットワーク上に置き、パブリックなイングレスから除外してください。ジェネレーターの設定とリクエスト制限を参照してください。

付属のユーティリティを使用してトークンを生成してください。

go run ./cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key "your-jwe-encryption-secret" \
  --jwt-secret-key "your-jwt-signing-secret" \
  --host "clickhouse.example.com" \
  --port 8123 \
  --database "analytics" \
  --username "user123" \
  --password "password123" \
  --expiry 86400

詳しくは、jwe_authentication.mdを参照してください。

TLS 設定

ClickHouse® TLS

./altinity-mcp \
  --clickhouse-tls \
  --clickhouse-tls-ca-cert /path/to/ca.crt \
  --clickhouse-tls-client-cert /path/to/client.crt \
  --clickhouse-tls-client-key /path/to/client.key

サーバー TLS

./altinity-mcp \
  --transport https \
  --server-tls \
  --server-tls-cert-file /path/to/server.crt \
  --server-tls-key-file /path/to/server.key

開発とテスト

開発ワークフロー、ビルドコマンド、テストの段階、および任意の OAuth Docker E2E フローについては、docs/development_and_testing.mdに記載されています。

OAuth の設定全般と ClickHouse 固有の詳細については、OAuth 2.0 認証ドキュメントを参照してください。

CLI リファレンス

グローバルフラグ

• --config: 設定ファイルのパス（YAML または JSON）
• --log-level: ログレベル（debug/info/warn/error）
• --clickhouse-limit: クエリ結果のデフォルト上限（デフォルト：1000）
• --openapi: OpenAPI エンドポイントを有効化（disable/http/https）（デフォルト：disable）

ClickHouse® フラグ

• --clickhouse-host: ClickHouse® サーバーのホスト
• --clickhouse-connect-host: 基盤となる TCP 接続にのみ使用する任意のホスト名または IP アドレス（CLICKHOUSE_CONNECT_HOST）
• --clickhouse-port: ClickHouse® サーバーのポート
• --clickhouse-database: データベース名
• --clickhouse-username: ユーザー名
• --clickhouse-password: パスワード
• --clickhouse-protocol: プロトコル（http/tcp）
• --read-only: 読み取り専用モード（読み取り以外の SQL を防ぎ、セッション変数の設定を回避します）
• --clickhouse-max-execution-time: クエリのタイムアウト（秒）
• --clickhouse-http-headers: ClickHouse リクエストの HTTP ヘッダー（key=value のペア）

サーバーフラグ

• --transport: トランスポートの種類（stdio/http/sse）
• --address: サーバーのアドレス
• --port: サーバーのポート
• --allow-jwe-auth: JWE 認証を有効化
• --jwe-secret-key: JWE トークンの復号に使用するシークレットキー（A256KW では 32 バイトである必要があります）。
• --jwt-secret-key: JWT 署名の検証に使用するシークレットキー
• --jwe-tls-material-dir: JWE TLS ファイルパスのディレクトリ許可リスト（空の場合、トークンのファイルパスを拒否します）
• --jwe-token-generator: 管理者による JWE トークン発行を有効化（デフォルトは false、MCP_JWE_TOKEN_GENERATOR_ENABLED）
• --jwe-token-generator-admin-token: 32 バイト以上の管理者 Bearer シークレット（シークレットの注入には MCP_JWE_TOKEN_GENERATOR_ADMIN_TOKEN の使用を推奨）
• --jwe-token-generator-max-expiry-seconds: 発行するトークンの有効期間の最大値（デフォルトは 86400、MCP_JWE_TOKEN_GENERATOR_MAX_EXPIRY_SECONDS）

コマンド

• version: バージョン情報を表示
• test-connection: ClickHouse® 接続をテスト

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. テストを追加します
5. テストスイートを実行します
6. プルリクエストを送信します

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

サポート

サポートやご質問については、以下をご利用ください。

• GitHub Issues：https://github.com/altinity/altinity-mcp/issues
• メール：[email protected]