@lishenxydlgzs/aws-athena-mcp

@lishenxydlgzs/aws-athena-mcp

AWS Athena クエリを実行するための Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI アシスタントが AWS Athena データベースに対して SQL クエリを実行し、結果を取得できます。

使い方

1. 以下のいずれかの方法で AWS 認証情報を設定します。

   • AWS CLI の設定
   • 環境変数（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）
   • IAM ロール（AWS 上で実行する場合）

2. MCP 設定にサーバーを追加します。

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": ["-y", "@lishenxydlgzs/aws-athena-mcp"],
      "env": {
        // Required
        "OUTPUT_S3_PATH": "s3://your-bucket/athena-results/",
        
        // Optional AWS configuration
        "AWS_REGION": "us-east-1",                    // Default: AWS CLI default region
        "AWS_PROFILE": "default",                     // Default: 'default' profile
        "AWS_ACCESS_KEY_ID": "",                      // Optional: AWS access key
        "AWS_SECRET_ACCESS_KEY": "",                  // Optional: AWS secret key
        "AWS_SESSION_TOKEN": "",                      // Optional: AWS session token
        
        // Optional server configuration
        "ATHENA_WORKGROUP": "default_workgroup",      // Optional: specify the Athena WorkGroup
        "QUERY_TIMEOUT_MS": "300000",                 // Default: 5 minutes (300000ms)
        "MAX_RETRIES": "100",                         // Default: 100 attempts
        "RETRY_DELAY_MS": "500"                       // Default: 500ms between retries
      }
    }
  }
}

3. サーバーでは以下のツールを利用できます。

• run_query：AWS Athena を使用して SQL クエリを実行します。

  • パラメーター：
    • database：クエリ対象の Athena データベース
    • query：実行する SQL クエリ
    • maxRows：返す行数の最大値（デフォルト：1000、最大：10000）
  • 戻り値：
    • タイムアウト内にクエリが完了した場合：クエリ結果全体
    • タイムアウトに達した場合：後で取得するための queryExecutionId のみ

• get_status：クエリ実行のステータスを確認します。

  • パラメーター：
    • queryExecutionId：run_query から返された ID
  • 戻り値：
    • state：クエリの状態（QUEUED、RUNNING、SUCCEEDED、FAILED、または CANCELLED）
    • stateChangeReason：状態が変更された理由（該当する場合）
    • submissionDateTime：クエリが送信された日時
    • completionDateTime：クエリが完了した日時（完了済みの場合）
    • statistics：クエリ実行の統計情報（利用可能な場合）

• get_result：完了したクエリの結果を取得します。

  • パラメーター：
    • queryExecutionId：run_query から返された ID
    • maxRows：返す行数の最大値（デフォルト：1000、最大：10000）
  • 戻り値：
    • クエリが正常に完了している場合は、クエリ結果全体
    • クエリが失敗した場合、または実行中の場合はエラー

• list_saved_queries：Athena に保存されている（名前付き）クエリをすべて一覧表示します。

• 戻り値：

  • id、name、および省略可能な description を含む保存済みクエリの配列
  • クエリは設定された ATHENA_WORKGROUP と AWS_REGION から返されます

• run_saved_query：保存済みクエリの ID を指定して実行します。

• パラメーター：

  • namedQueryId：保存済みクエリの ID
  • databaseOverride：保存済みクエリのデフォルトのデータベースを上書きする場合に指定します（省略可能）
  • maxRows：返す行数の最大値（デフォルト：1000）
  • timeoutMs：タイムアウトまでの時間（ミリ秒）（デフォルト：60000）

• 戻り値：

  • run_query と同じ動作で、結果全体または実行 ID を返します

---

使用例

すべてのデータベースを表示

AI アシスタントへのメッセージ： List all databases in Athena

MCP parameter:

{
  "database": "default",
  "query": "SHOW DATABASES"
}

データベース内のテーブルを一覧表示

AI アシスタントへのメッセージ： Show me all tables in the default database

MCP parameter:

{
  "database": "default",
  "query": "SHOW TABLES"
}

テーブルスキーマを取得

AI アシスタントへのメッセージ： What's the schema of the asin_sitebestimg table?

MCP parameter:

{
  "database": "default",
  "query": "DESCRIBE default.asin_sitebestimg"
}

テーブルの行をプレビュー

AI アシスタントへのメッセージ： Show some rows from my_database.mytable

MCP parameter:

{
  "database": "my_database",
  "query": "SELECT * FROM my_table LIMIT 10",
  "maxRows": 10
}

フィルタリングと集計を行う高度なクエリ

AI アシスタントへのメッセージ： Find the average price by category for in-stock products

MCP parameter:

{
  "database": "my_database",
  "query": "SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products WHERE in_stock = true GROUP BY category ORDER BY count DESC",
  "maxRows": 100
}

クエリのステータスを確認

{
  "queryExecutionId": "12345-67890-abcdef"
}

完了したクエリの結果を取得

{
  "queryExecutionId": "12345-67890-abcdef",
  "maxRows": 10
}

保存済みクエリを一覧表示

{
  "name": "list_saved_queries",
  "arguments": {}
}

保存済みクエリを実行

{
  "name": "run_saved_query",
  "arguments": {
    "namedQueryId": "abcd-1234-efgh-5678",
    "maxRows": 100
  }
}

---

要件

• Node.js >= 16
• 適切な Athena および S3 の権限を持つ AWS 認証情報
• クエリ結果を保存する S3 バケット
• 名前付きクエリ（省略可能）は、指定された ATHENA_WORKGROUP と AWS_REGION に存在している必要があります

---

ライセンス

MIT

リポジトリ

GitHub リポジトリ