Aws Athena MCP

🚀 @lishenxydlgzs/aws-athena-mcp

A Model Context Protocol (MCP) server for running AWS Athena queries. This server enables AI assistants to execute SQL queries on your AWS Athena database and retrieve results.

🚀 Quick Start

📦 Installation

Install the package using the following command:

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

⚙️ Configuration

Environment Variables

Set the following environment variables to enable AWS authentication:

# Enable AWS authentication
export AWS_ENABLED=true

# Set AWS region
export AWS_REGION=us-east-1  # Example region, modify as needed

✨ Features

The MCP server supports the following features:

• Query Execution: Execute SQL queries via HTTP requests.
• Result Storage: Save query results to a specified S3 bucket.
• Status Check: Provide functionality to check the status of running or completed queries.

💻 Usage Examples

🔍 Basic Query

Request Body:

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

Response Body:

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

📊 Status Check

Request Body:

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

Response Body:

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

📚 Documentation

📋 Execution Query Parameters

📋 Status Check Parameters

📄 Return Result Format

The results of all query operations will be returned in JSON format, including the status code, error information (if any), and query results or status details.

🔧 Technical Details

🚪 API Endpoints

/api/v1/execute

• Method: POST
• Description: Execute a given SQL query.

Request Body Example:

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

Response Body Example:

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

/api/v1/status

• Method: GET
• Description: Check the execution status of a specified query.

Request Parameters:

# Example curl request
curl -X GET "http://localhost:3000/api/v1/status?executionId=1234-5678-90ab-cdef"

Response Body Example:

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

⚠️ Important Note

• Ensure that your AWS credentials have the necessary permissions to execute Athena queries and access the S3 bucket.
• Configure appropriate error handling mechanisms to handle query failures.

📄 License

This project is licensed under the MIT License.

🌐 Project Repository

GitHub Repository