JinDaGe - aws-athena-mcp MCP Details

article

README

🚀 @lishenxydlgzs/aws-athena-mcp

这是一个用于运行 AWS Athena 查询的模型上下文协议（MCP）服务器，借助该服务器，AI 助手能够对您的 AWS Athena 数据库执行 SQL 查询并获取结果。

🚀 快速开始

安装步骤

使用以下命令进行安装：

npm install --save @lishenxydlgzs/aws-athena-mcp

配置说明

环境变量配置

设置以下环境变量以启用 AWS 认证：

# 启用 AWS 认证
export AWS_ENABLED=true

# 设置 AWS 区域
export AWS_REGION=us-east-1  # 示例区域，根据需要修改

✨ 主要特性

该 MCP 服务器支持以下功能：

查询执行：通过 HTTP 请求执行 SQL 查询。
结果存储：将查询结果保存到指定的 S3 存储桶中。
状态检查：提供对正在运行或已完成查询的状态进行检查的功能。

💻 使用示例

基础用法

示例 1: 基本查询

请求体：

{
  "name": "execute_query",
  "arguments": {
    "database": "default",
    "query": "SELECT * FROM my_table LIMIT 5"
  }
}

响应体：

{
  "status": "success",
  "data": {
    "queryExecutionId": "1234-5678-90ab-cdef",
    "resultLocation": "s3://my-bucket/results/1234-5678.csv"
  }
}

示例 2: 状态检查

请求体：

{
  "name": "get_query_status",
  "arguments": {
    "queryExecutionId": "1234-5678-90ab-cdef"
  }
}

响应体：

{
  "status": "success",
  "data": {
    "executionStatus": "SUCCEEDED",
    "stateChangeTime": "2023-10-01T00:00:00.000Z"
  }
}

📚 详细文档

参数说明

执行查询参数

| 参数名称 | 类型 | 是否必填 | 描述 | | ---- | ---- | ---- | ---- | | database | String | 是 | 要查询的数据库名称 | | query | String | 是 | 需要执行的 SQL 查询语句 | | maxRows | Integer | 否 | 返回的最大行数，默认为 100 |

状态检查参数

| 参数名称 | 类型 | 是否必填 | 描述 | | ---- | ---- | ---- | ---- | | queryExecutionId | String | 是 | 查询的唯一标识符 |

返回结果格式

所有查询操作的结果将返回 JSON 格式的数据，包含状态码、错误信息（如有）以及查询结果或状态详情。

接口设计

该 MCP 服务器提供以下 API 端点：

`/api/v1/execute`

方法：POST
描述：执行给定的 SQL 查询。

请求体示例：

{
  "name": "execute_query",
  "arguments": {
    "database": "default",
    "query": "SELECT * FROM users LIMIT 5"
  }
}

响应体示例：

{
  "status": "success",
  "data": {
    "executionId": "1234-5678-90ab-cdef",
    "message": "Query is being executed."
  }
}

`/api/v1/status`

方法：GET
描述：检查指定查询的执行状态。

请求参数：

# 示例 curl 请求
curl -X GET "http://localhost:3000/api/v1/status?executionId=1234-5678-90ab-cdef"

响应体示例：

{
  "status": "success",
  "data": {
    "executionStatus": "SUCCEEDED",
    "resultLocation": "s3://my-bucket/results/1234-5678.csv",
    "createTime": "2023-10-01T00:00:00.000Z"
  }
}

⚠️ 注意事项

⚠️ 重要提示

确保 AWS 凭证具有执行 Athena 查询和访问 S3 存储桶的权限。

配置合适的错误处理机制以应对查询失败的情况。

📄 许可证

本项目采用 MIT 许可证。

项目仓库

GitHub 仓库

aws-athena-mcp