AWS Athena MCP Server

AWS Athena MCP サーバー

n8n AI エージェントとの連携を目的とした、AWS Athena 用の Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーは、n8n AI エージェントが AWS Athena にクエリを実行し、データを取得するための標準化された方法を提供します。Model Context Protocol を実装しており、n8n エージェントは次の操作を行えます。

1. 利用可能なデータベースとテーブルを一覧表示する
2. テーブルのスキーマとメタデータを取得する
3. SQL クエリを実行して結果を取得する

特長

• n8n AI エージェントから Athena を操作するためのシンプルな API
• ヘルスチェックとモニタリングを組み込み
• 環境変数による設定が可能
• デプロイしやすいコンテナ化
• EKS のマニフェスト例を含む、Kubernetes 対応

前提条件

• Athena にアクセスできる AWS アカウント
• 適切な権限を持つ AWS 認証情報
• ローカルでの開発／テスト用の Docker
• 本番環境へのデプロイ用の Kubernetes／EKS

環境変数

サーバーは次の環境変数を使用して設定します。

変数	説明	デフォルト
AWS_REGION	Athena の AWS リージョン	us-east-1
ATHENA_CATALOG	Athena のカタログ名	AwsDataCatalog
ATHENA_DATABASE	使用するデフォルトのデータベース	なし
ATHENA_WORKGROUP	使用する Athena ワークグループ	primary
ATHENA_OUTPUT_LOCATION	クエリ結果の S3 ロケーション	なし（必須）
HOST	サーバーをバインドするホスト	0.0.0.0
PORT	リッスンするポート	8050

利用可能なツール

MCP サーバーは、n8n AI エージェントに次のツールを提供します。

execute_query

Athena に対して SQL クエリを実行し、結果を取得します。

パラメーター：

• query（string、必須）：実行する SQL クエリ
• database（string、任意）：データベース名
• catalog（string、任意）：カタログ名
• output_location（string、任意）：結果の S3 ロケーション
• workgroup（string、任意）：ワークグループ名
• max_results（integer、任意）：返す結果の最大件数
• max_wait_seconds（integer、任意）：クエリ完了までの最大待機時間

list_databases

カタログ内の利用可能なデータベースを一覧表示します。

パラメーター：

• catalog（string、任意）：カタログ名

list_tables

指定したデータベース内のテーブルを一覧表示します。

パラメーター：

• database（string、必須）：データベース名
• catalog（string、任意）：カタログ名

get_table_metadata

列定義など、指定したテーブルのメタデータを取得します。

パラメーター：

• table（string、必須）：テーブル名
• database（string、必須）：データベース名
• catalog（string、任意）：カタログ名

ローカル開発

インストール

1. リポジトリをクローンします。

git clone https://github.com/yourusername/aws-athena-mcp-server.git
cd aws-athena-mcp-server

2. 依存関係をインストールします。

pip install -r requirements.txt

3. AWS 認証情報を設定します。

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=your_region
export ATHENA_OUTPUT_LOCATION=s3://your-bucket/folder/

4. サーバーを起動します。

python main.py

サーバーは http://localhost:8050 で利用できます。

Docker のセットアップ

Docker イメージのビルド

docker build -t athena-mcp-server:latest .

Docker コンテナの実行

docker run -p 8050:8050 \
  -e AWS_REGION=us-east-1 \
  -e ATHENA_OUTPUT_LOCATION=s3://your-bucket/folder/ \
  -e AWS_ACCESS_KEY_ID=your_access_key \
  -e AWS_SECRET_ACCESS_KEY=your_secret_key \
  athena-mcp-server:latest

AWS EKS へのデプロイ

前提条件

• 適切な権限で設定済みの AWS CLI
• kubectl がインストールされ、EKS クラスターへの接続が設定されていること
• イメージのビルド用に Docker がインストールされていること

デプロイ手順

1. Docker イメージをビルドして ECR にプッシュします。

# Create ECR repository if it doesn't exist
aws ecr create-repository --repository-name athena-mcp-server

# Get ECR login command
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ${AWS_ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com

# Build and tag the image
docker build -t ${AWS_ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com/athena-mcp-server:latest .

# Push the image to ECR
docker push ${AWS_ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com/athena-mcp-server:latest

2. EKS サービスアカウント用の IAM ロールを作成します。

# Create IAM policy
aws iam create-policy \
  --policy-name AthenaQueryPolicy \
  --policy-document file://k8s/aws-policy.json

# Create IAM role for service account (IRSA)
eksctl create iamserviceaccount \
  --name athena-mcp-server \
  --namespace default \
  --cluster your-eks-cluster \
  --attach-policy-arn arn:aws:iam::${AWS_ACCOUNT_ID}:policy/AthenaQueryPolicy \
  --approve \
  --override-existing-serviceaccounts

3. Kubernetes マニフェスト内のプレースホルダーを実際の値に置き換えます。

export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export AWS_REGION=us-east-1
export ATHENA_DEFAULT_DATABASE=your_database
export ATHENA_WORKGROUP=primary
export ATHENA_OUTPUT_LOCATION=s3://your-bucket/athena-results/

# Replace variables in YAML files
envsubst < k8s/deployment.yaml > k8s/generated/deployment.yaml
envsubst < k8s/serviceaccount.yaml > k8s/generated/serviceaccount.yaml

4. Kubernetes マニフェストを適用します。

kubectl apply -f k8s/generated/serviceaccount.yaml
kubectl apply -f k8s/generated/deployment.yaml
kubectl apply -f k8s/generated/service.yaml

5. デプロイを確認します。

kubectl get pods -l app=athena-mcp-server
kubectl get service athena-mcp-server

6. 外部からのアクセスが必要な場合は、（任意で）Ingress リソースを作成します。

n8n との連携

この MCP サーバーを n8n で使用するには、次の手順を実行します。

1. MCP サーバーをインフラストラクチャにデプロイします
2. n8n AI Agent ノードに適切なシステムプロンプトを設定します（docs/n8n_system_prompt_template.md を参照）
3. n8n から MCP サーバーのエンドポイントに接続します

n8n AI エージェントのシステムプロンプトテンプレート

n8n AI Agent ノードのシステムプロンプトには、docs/n8n_system_prompt_template.md のテンプレートを使用してください。このテンプレートは、AI が以下を行う際のガイドとなります。

• データベーススキーマを理解する
• 効率的な SQL クエリを作成する
• MCP サーバー経由でクエリを実行する
• 結果をわかりやすく提示する

テンプレートを、利用する Athena データベースの構造や一般的なクエリパターンに合わせてカスタマイズしてください。

ドキュメント

追加のドキュメントは docs/ ディレクトリにあります。

• n8n_system_prompt_template.md：n8n AI Agent のシステムプロンプトのテンプレート
• implementation_guide.md：詳細な実装ガイド
• architecture.md：アーキテクチャ図と説明
• troubleshooting.md：一般的な問題の解決方法
• n8n_integration_example.md：n8n ワークフローの例
• examples/：特定のユースケース向けのプロンプト例が含まれるディレクトリ

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します。お気軽に Pull Request を送信してください。