athena-mcp

current version: 0.2.0

MCP server for the Athena database gateway. Exposes Athena's PostgreSQL management API as MCP tools for use with LLM agents and AI coding assistants.

Tool calls

Schema & Data

• list_tables: List all tables available in the connected database
• list_schemas: List database schemas visible to the current client
• list_extensions: List all PostgreSQL installed extensions
• list_views: List views that are visible and optionally materialized views
• list_foreign_keys: List primary keys, foreign keys and unique constraints for a table
• list_indexes: List index definitions for a table
• list_all_table_metadata: Return metadata for all tables in one call: schema, name, columns, types, defaults, nullable
• list_table_metadata: Returns the full metadata for a table: schema_name, table_name and each column's name, type, default value and nullable flag
• get_columns_of_table: Describe columns for a table using Athena's schema API
• search_columns: Find tables and columns by name pattern
• get_table_sample: Sample rows from a table to understand its data shape. Quick alternative to writing SQL
• execute_sql: Execute a raw SQL query, write is blocked when read_only mode is enabled
• get_row_by_id: Fetch rows by primary key column value. Simplifies the common fetch-by-id use case
• get_row_by_eq_column_of_table: Fetch rows from a table where column = value using Athena's fetch endpoint
• insert_row: Insert a row into a table. Blocked when read_only mode is enabled
• update_row: Update rows matching a condition. Blocked when read_only mode is enabled
• delete_row: Delete a row by primary key (resource_id). Blocked when read_only mode is enabled

Migrations & Logs

• list_migrations: List applied database migrations
• apply_migration: Apply a SQL migration against a connected DB, blocked when read_only mode is enabled
• get_logs: Retrieve recent database or application logs

Health & Infrastructure

• ping: Run Athena's /ping health check
• get_api_root: Fetch Athena API root metadata and advertised routes
• get_cluster_health: Check mirror reachability, latency, throughput, and version metadata
• get_management_capabilities: List management API capabilities and required rights for the current client

Table Management

• create_table: Create a managed table via Athena's management API. Blocked when read_only mode is enabled
• edit_table: Apply safe additive ALTER TABLE operations. Blocked when read_only mode is enabled
• drop_table: Drop a managed table. Blocked when read_only mode is enabled
• drop_column: Drop a managed table column. Blocked when read_only mode is enabled
• create_index: Create an index via the management API. Blocked when read_only mode is enabled
• drop_index: Drop an index via the management API. Blocked when read_only mode is enabled

Pipelines

• run_pipeline: Run a config-driven Athena pipeline (source → transform → sink)

Clients

• list_available_clients: List Athena/Postgres clients available to the current admin key
• list_athena_clients_admin: List Athena clients from the database-backed admin catalog
• create_athena_client: Create an Athena client in the admin catalog. Blocked when read_only mode is enabled
• update_athena_client: Update an Athena client in the admin catalog. Blocked when read_only mode is enabled
• delete_athena_client: Soft-delete an Athena client from the admin catalog. Blocked when read_only mode is enabled
• freeze_athena_client: Freeze or unfreeze an Athena client. Blocked when read_only mode is enabled
• list_client_statistics: List aggregated Athena client statistics
• refresh_client_statistics: Rebuild Athena client statistics. Blocked when read_only mode is enabled
• get_client_statistics: Inspect per-client statistics and touched tables

API Keys

• list_api_keys: List Athena API keys
• create_api_key: Create an Athena API key. Blocked when read_only mode is enabled
• update_api_key: Update an existing Athena API key. Blocked when read_only mode is enabled
• delete_api_key: Delete an Athena API key. Blocked when read_only mode is enabled
• list_api_key_rights: List available Athena API key rights
• create_api_key_right: Create an Athena API key right. Blocked when read_only mode is enabled
• update_api_key_right: Update an Athena API key right. Blocked when read_only mode is enabled
• delete_api_key_right: Delete an Athena API key right. Blocked when read_only mode is enabled
• get_api_key_config: Read the global Athena API key enforcement configuration
• update_api_key_config: Update global API key enforcement config. Blocked when read_only mode is enabled
• list_api_key_clients: List per-client API key enforcement overrides
• save_api_key_client: Create or update a per-client enforcement override. Blocked when read_only mode is enabled
• delete_api_key_client: Delete a per-client enforcement override. Blocked when read_only mode is enabled

Registry & Monitoring

• list_router_registry: List Athena router registry entries
• list_registry_entries: List API registry entries from Athena
• get_registry_entry: Fetch a specific API registry entry by ID
• get_metrics: Fetch Athena's Prometheus metrics payload
• get_embedded_openapi: Download Athena's embedded OpenAPI YAML document
• get_websocket_info: Read Athena's websocket gateway contract metadata
• toggle_supabase_ssl_enforcement: Enable or disable Supabase SSL enforcement. Blocked when read_only mode is enabled

Install

npm install @xylex-group/athena-mcp

npx -y --package=git+https://github.com/xylex-group/athena-mcp.git athena-mcp --version

Or run without installing:

npx -y --package=git+https://github.com/xylex-group/athena-mcp.git athena-mcp

Or from npm:

npx -y @xylex-group/athena-mcp

Adding to AI coding assistants

Cursor

1. Open Cursor Settings → Cursor Tab → MCP (or Cmd/Ctrl + , → search "MCP")
2. Click Add new MCP server and configure:
   • Name: athena
   • Type: Command
   • Command: npx
   • Args: -y, --package=git+https://github.com/xylex-group/athena-mcp.git, athena-mcp
   • Env: Add ATHENA_API_KEY, ATHENA_CLIENT (for X-Athena-Client header), READ_ONLY, etc.

Or add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/xylex-group/athena-mcp.git",
        "athena-mcp",
        "--athena-api-key=api-key-1234567890",
        "--athena-client=railway_direct",
        "--read-only=false"
      ]
    }
  }
}

Or use env (good for secrets):

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": ["-y", "--package=git+https://github.com/xylex-group/athena-mcp.git", "athena-mcp"],
      "env": {
        "ATHENA_API_KEY": "api-key-1234567890",
        "ATHENA_CLIENT": "railway_direct",
        "READ_ONLY": "false"
      }
    }
  }
}

Restart Cursor after changing the config.

VSCode

VSCode supports MCP through extensions like Continue or through the native GitHub Copilot (if you have access to MCP features).

Using Continue Extension

1. Install the Continue extension from the VSCode marketplace
2. Open Continue settings (click the Continue icon in the sidebar → settings gear)
3. Add the MCP server to your config.json:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/xylex-group/athena-mcp.git",
        "athena-mcp"
      ],
      "env": {
        "ATHENA_API_KEY": "<your-api-key>",
        "ATHENA_CLIENT": "railway_direct",
        "READ_ONLY": "true"
      }
    }
  }
}

Using GitHub Copilot (with MCP support)

Note: GitHub Copilot's MCP integration is evolving and may not yet be publicly available. The configuration structure shown below is illustrative and may differ from the actual implementation. Please check the official GitHub Copilot documentation for the most current and accurate MCP setup instructions.

If you have access to GitHub Copilot's MCP features:

1. Open VSCode Settings → search for "MCP"
2. Edit the MCP configuration file (typically settings.json or a dedicated MCP config)
3. Add the athena server configuration (example structure):

{
  "github.copilot.advanced": {
    "mcp": {
      "servers": {
        "athena": {
          "command": "npx",
          "args": [
            "-y",
            "--package=git+https://github.com/xylex-group/athena-mcp.git",
            "athena-mcp"
          ],
          "env": {
            "ATHENA_API_KEY": "<your-api-key>",
            "ATHENA_CLIENT": "railway_direct",
            "READ_ONLY": "true"
          }
        }
      }
    }
  }
}

Reload VSCode after making changes.

Claude Code

Add the server via CLI:

claude mcp add athena -- npx -y --package=git+https://github.com/xylex-group/athena-mcp.git athena-mcp

Or edit the config file directly:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/xylex-group/athena-mcp.git",
        "athena-mcp"
      ],
      "env": {
        "ATHENA_API_KEY": "<your-api-key>",
        "ATHENA_CLIENT": "railway_direct",
        "READ_ONLY": "true"
      }
    }
  }
}

For project scope, create .mcp.json in your project root and run claude mcp add --scope project athena -- npx -y --package=git+https://github.com/xylex-group/athena-mcp.git athena-mcp.

Windsurf

1. Go to Plugins → Manage plugins → View raw config
2. Add the athena server to the JSON config:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/xylex-group/athena-mcp.git",
        "athena-mcp"
      ],
      "env": {
        "ATHENA_API_KEY": "<your-api-key>",
        "ATHENA_CLIENT": "railway_direct",
        "READ_ONLY": "true"
      }
    }
  }
}

1. Save and refresh Windsurf.

Zed

1. Open Settings → Features → AI → MCP
2. Add a custom server with:
   • Name: athena
   • Command: npx
   • Args: -y, --package=git+https://github.com/xylex-group/athena-mcp.git, athena-mcp
   • Env: ATHENA_API_KEY, ATHENA_CLIENT, READ_ONLY, etc.

Or edit the MCP config JSON in Zed settings and add the same athena entry as above.

Tools

Tool schemas are documented in mcp-tools.json (MCP-native) and athena-mcp-openapi.yaml (OpenAPI 3.0).

Configuration

Set the following environment variables before starting the server:

These can also be passed as CLI args (override env vars):

npx -y --package=git+https://github.com/xylex-group/athena-mcp.git athena-mcp --athena-base-url=https://api.example.com --athena-api-key=xxx --athena-client=railway_direct --read-only

Or with the published package:

npx -y @xylex-group/athena-mcp --athena-base-url=https://api.example.com --athena-api-key=xxx --athena-client=railway_direct --read-only

Read-only mode

When READ_ONLY=true:

• apply_migration, insert_row, delete_row, update_row, create_table, edit_table, drop_table, drop_column, create_index, drop_index, create_api_key, update_api_key, delete_api_key, create_api_key_right, update_api_key_right, delete_api_key_right, update_api_key_config, save_api_key_client, delete_api_key_client, create_athena_client, update_athena_client, delete_athena_client, freeze_athena_client, refresh_client_statistics, and toggle_supabase_ssl_enforcement return an error immediately.
• execute_sql rejects queries containing write keywords (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE, REPLACE).

Usage (generic MCP config)

Most MCP clients use this format:

{
  "mcpServers": {
    "athena": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/xylex-group/athena-mcp.git",
        "athena-mcp"
      ],
      "env": {
        "ATHENA_API_KEY": "<your-api-key>",
        "ATHENA_CLIENT": "railway_direct",
        "READ_ONLY": "true"
      }
    }
  }
}

Development

npm install
npm run build      # tsup (default, fast)
npm run build:tsc  # plain TypeScript compiler
npm run build:rollup  # Rollup bundle
npm start

Testing

npm run test        # Run tests once
npm run test:watch  # Run tests in watch mode

Linting

npm run lint       # Check for issues
npm run lint:fix   # Auto-fix issues