AWS Athena MCP Server

AWS Athena MCP 服务

一个用于 AWS Athena 的模型上下文协议（MCP）服务，旨在与 n8n AI Agent 集成。

概述

此 MCP 服务为 n8n AI Agent 提供了一种标准化的方式来查询 AWS Athena 并检索数据。它实现了模型上下文协议，使 n8n Agent 能够：

1. 列出可用的数据库和表
2. 获取表架构和元数据
3. 执行 SQL 查询并检索结果

功能

• 为 n8n AI Agent 提供与 Athena 交互的简易 API
• 内置运行状况检查和监控
• 可通过环境变量进行配置
• 容器化，便于部署
• 支持 Kubernetes，并提供示例 EKS 清单

前提条件

• 拥有 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 Agent 提供以下工具：

execute_query

对 Athena 执行 SQL 查询并检索结果。

参数：

• query（字符串，必填）：要执行的 SQL 查询
• database（字符串，可选）：数据库名称
• catalog（字符串，可选）：目录名称
• output_location（字符串，可选）：结果的 S3 位置
• workgroup（字符串，可选）：工作组名称
• max_results（整数，可选）：要返回的最大结果数
• max_wait_seconds（整数，可选）：等待查询完成的最长时间

list_databases

列出目录中的可用数据库。

参数：

• catalog（字符串，可选）：目录名称

list_tables

列出指定数据库中的表。

参数：

• database（字符串，必填）：数据库名称
• catalog（字符串，可选）：目录名称

get_table_metadata

获取指定表的元数据，包括列定义。

参数：

• table（字符串，必填）：表名称
• database（字符串，必填）：数据库名称
• catalog（字符串，可选）：目录名称

本地开发

安装

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 集成

要在 n8n 中使用此 MCP 服务：

1. 将 MCP 服务部署到你的基础设施
2. 使用适当的系统提示词配置 n8n AI Agent 节点（参见 docs/n8n_system_prompt_template.md）
3. 从 n8n 连接到 MCP 服务端点

n8n AI Agent 系统提示词模板

使用 docs/n8n_system_prompt_template.md 中的模板作为 n8n AI Agent 节点的系统提示词。此模板可指导 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

贡献

欢迎贡献！请随时提交拉取请求。