AWS Athena

You can run an MCP server for AWS Athena to run SQL queries and explore databases through a standardized interface. This server connects your MCP client to Athena, enabling you to execute queries and retrieve results in a consistent, tool-friendly way.

How to use

Start the Athena MCP server locally and connect to it from your MCP client. You will run a stdio-based server that executes the main Python entry point to communicate with AWS Athena. The available actions include listing databases, executing SQL queries, and describing data structures. Use your MCP client to browse databases, run queries, and inspect schemas through the server’s exposed capabilities.

How to install

Prerequisites: Python 3.8+ and a working Python environment. You may also want docker or a virtual environment, but the following steps assume a direct Python install.

1. Install Python dependencies in development mode (optional if you only need production). Run these commands from your project root.

# Install in development mode for a local workflow
pip install -e .[dev]

2. Install the runtime dependencies for production (if you prefer a clean install without dev tools). Run:

pip install .

3. Prepare your environment and start the server using the standard entry point described below.

# Run via the main entry point
python main.py

# Or use the installed command if available
athena-mcp

Configuration and environment

Configure the MCP client to launch the Athena MCP server using a local stdio bridge. The MCP configuration uses a command to start Python and run the main entry script, with AWS credentials and settings supplied via environment variables.

{
  "mcpServers": {
    "athena_mcp": {
      "command": "python3",
      "args": ["/path/to/aws-athena-mcp/main.py"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_REGION": "us-east-1",
        "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/"
      }
    }
  }
}

Security and credentials

Prefer AWS profiles or IAM roles over embedding credentials directly in configuration. When running locally, you can use AWS_PROFILE to specify your local credentials, or rely on system-default credentials if configured.

Be mindful of the AWS_REGION and S3 output location. Ensure the S3 bucket exists and you have the necessary permissions to write query results.

Notes and best practices

Keep your dependencies up to date and use a virtual environment to isolate this server from other Python projects. Maintain clear separation between production and development environments.

Log at an appropriate level to balance observability with performance. Use structured logging to make debugging easier.

Troubleshooting

If you encounter permission errors writing to S3, verify your IAM policy and the S3 bucket policy. If the server cannot connect to Athena, check your AWS_REGION and network access. Review your AWS credentials and session tokens if needed.

Example MCP server configuration (stdio)

{
  "type": "stdio",
  "name": "athena_mcp",
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_ACCESS_KEY_ID": "your-access-key",
    "AWS_SECRET_ACCESS_KEY": "your-secret-key",
    "AWS_REGION": "us-east-1",
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/"
  }
}

Available tools

list_databases

Lists all available databases in Athena.

query_athena

Executes SQL queries in Athena and returns results.

describe_data_structure

Describes the structure of a database to reveal tables, columns, and data types.