Teradata MCP Server

Teradata MCP サーバー

OAuth 2.1 認証、複数の認証方式（TD2、LDAP、Kerberos）、インタラクティブなデータ可視化に対応した、Teradata データベース用の Model Context Protocol（MCP）サーバーです。

機能

• 複数の認証方式 — TD2（デフォルト）、LDAP、Kerberos、Teradata の LOGMECH を介した JWT
• OAuth 2.1 と Keycloak の統合、JWT 検証、スコープベースの認可
• 保護されたリソースのメタデータ（RFC 9728 準拠）
• インタラクティブな可視化 — 19 種類のチャートに対応した ECharts ベースの MCP App
• 接続の回復性 — 指数バックオフによる自動再試行
• ノンブロッキング I/O — すべての DB 操作を asyncio.to_thread() 経由で実行
• ツールごとの QueryBand — Teradata ワークロード管理の監査証跡

ツール

クエリツール

• query — SQL クエリを実行し、プレーンな表形式の結果を返します
• visualize_query — SQL を実行し、MCP App 経由でインタラクティブな ECharts チャートを表示します

スキーマツール

• list_db — すべてのデータベースを一覧表示します
• list_tables — データベース内のテーブル／ビューを一覧表示します
• show_tables_details — テーブルの列名とデータ型を表示します

分析ツール

• list_missing_values — NULL 値の件数を列ごとに表示します
• list_negative_values — 負の値の件数を列ごとに表示します
• list_distinct_values — 列ごとの個別カテゴリ数を表示します
• standard_deviation — 列の平均値と標準偏差を表示します

MCP App — インタラクティブな可視化

visualize_query ツールは、結果を MCP クライアント内にインタラクティブなチャートとして表示します。

カテゴリ	チャート
棒グラフ	基本、グループ化、積み上げ、横向き、並べ替え、ウォーターフォール、角丸、極座標
折れ線グラフ	基本、スムーズ、面、積み上げ面、ステップ
円グラフ	円グラフ、ドーナツ、ローズ／ナイチンゲール
散布図	散布図、バブル
複合グラフ	棒グラフ＋折れ線グラフ

クイックスタート

インストール

git clone https://github.com/arturborycki/mcp-teradata.git
cd mcp-teradata
uv sync

TD2 で実行（標準認証）

uv run teradata-mcp "teradatasql://user:password@host/database"

または、環境変数で指定します。

export DATABASE_URI="teradatasql://user:password@host/database"
uv run teradata-mcp

設定

Claude Desktop

claude_desktop_config.json に追加します。

TD2（ユーザー名／パスワード）

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database"
      }
    }
  }
}

LDAP 認証

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "LDAP",
        "DB_LOGDATA": "authcid=ldap_user password=ldap_password"
      }
    }
  }
}

authcid の形式は LDAP ディレクトリによって異なります。

ディレクトリ	形式
Active Directory（シンプルバインド）	[email protected]
Active Directory（DIGEST-MD5）	authcid=DOMAIN\username
OpenLDAP / Sun DS	authcid=username

Kerberos 認証

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://@host/database",
        "DB_LOGMECH": "KRB5"
      }
    }
  }
}

OAuth 対応の設定

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-teradata",
        "run", "teradata-mcp"
      ],
      "env": {
        "DATABASE_URI": "teradatasql://user:password@host/database",
        "OAUTH_ENABLED": "true",
        "KEYCLOAK_URL": "https://your-keycloak.example.com",
        "KEYCLOAK_REALM": "teradata-realm",
        "KEYCLOAK_CLIENT_ID": "teradata-mcp",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "OAUTH_RESOURCE_SERVER_URL": "https://your-mcp-server.example.com"
      }
    }
  }
}

環境変数

データベース接続

変数	説明	デフォルト
DATABASE_URI	Teradata 接続 URL（teradatasql://user:pass@host/db）	—
DB_LOGMECH	認証方式：TD2、LDAP、KRB5、TDNEGO、JWT	TD2
DB_LOGDATA	LDAP／JWT の認証情報（例：authcid=user password=pass）	—
DB_SSL_MODE	TLS モード：ALLOW、PREFER、REQUIRE、VERIFY-CA、VERIFY-FULL	—
DB_ENCRYPT_DATA	転送時の暗号化を有効にします	true

接続の回復性

変数	説明	デフォルト
DB_MAX_RETRIES	最大再接続試行回数	3
DB_INITIAL_BACKOFF	初期待機時間（秒）	1.0
DB_MAX_BACKOFF	最大待機時間（秒）	30.0

MCP トランスポート

変数	説明	デフォルト
MCP_TRANSPORT	トランスポート：stdio、sse、streamable-http	stdio
MCP_HOST	HTTP トランスポートのバインドアドレス	localhost
MCP_PORT	HTTP トランスポートのポート	8000
MCP_PATH	streamable-http のパス	/mcp/

OAuth 2.1

変数	説明	デフォルト
OAUTH_ENABLED	OAuth 認証を有効にします	false
KEYCLOAK_URL	Keycloak サーバーの URL	—
KEYCLOAK_REALM	Keycloak のレルム名	—
KEYCLOAK_CLIENT_ID	OAuth クライアント ID	—
KEYCLOAK_CLIENT_SECRET	OAuth クライアントシークレット	—
OAUTH_RESOURCE_SERVER_URL	リソースサーバーの URL	—
OAUTH_REQUIRED_SCOPES	必須スコープ（カンマ区切り）	—
OAUTH_VALIDATE_AUDIENCE	トークンのオーディエンスを検証します	true
OAUTH_VALIDATE_SCOPES	トークンのスコープを検証します	true
OAUTH_REQUIRE_HTTPS	OAuth URL に HTTPS を必須とします	true
CORS_ALLOWED_ORIGINS	CORS で許可するオリジン	*

OAuth スコープ

スコープ	説明
teradata:read	データベースリソースへの読み取りアクセス
teradata:write	データベースリソースへの書き込みアクセス
teradata:query	SQL クエリを実行します
teradata:admin	管理者アクセス
teradata:schema	スキーマ管理操作

トランスポートの互換性

トランスポート	OAuth	ディスカバリーエンドポイント	用途
stdio	該当なし	該当なし	Claude Desktop、CLI クライアント
SSE	フル対応	利用可能	ウェブアプリケーション
Streamable HTTP	フル対応	利用可能	API 統合

OAuth が有効な場合のディスカバリーエンドポイント：

• /.well-known/oauth-protected-resource — RFC 9728 メタデータ
• /.well-known/mcp-server-info — MCP の機能
• /health — ヘルスチェック

Docker のデプロイ

開発

docker compose up -d

OAuth を使用する場合

docker compose -f docker-compose.oauth.yml up -d

ビルド

uv build

トラブルシューティング

データベース接続の問題：

• DATABASE_URI の形式を確認します：teradatasql://user:pass@host/database
• Teradata サーバーへのネットワーク接続を確認します
• LDAP の場合：DB_LOGMECH=LDAP と DB_LOGDATA が正しく設定されていることを確認します
• 接続の問題は自動的に再試行されます（DB_MAX_RETRIES で設定可能）

LDAP 認証に失敗する場合：

• Teradata サーバーで TDGSS の LDAP が設定されていることを確認します
• authcid の形式がディレクトリの種類に合っていることを確認します
• パスワード内の特殊文字をエスケープします（@ → \@、スペース → 引用符を使用）

アクセス拒否エラー：

• ユーザーに必要な OAuth スコープがあることを確認します
• Keycloak のロール割り当てを確認します
• visualize_query には teradata:read だけでなく、teradata:query スコープが必要です

デバッグログ：

export LOG_LEVEL=DEBUG
uv run teradata-mcp

ライセンス

MIT License。詳細は LICENSE を参照してください。

謝辞

• Model Context Protocol
• Keycloak
• Teradata
• FastMCP