{"_id":"@lishenxydlgzs/aws-athena-mcp","_rev":"2-cb4e896c170b532fd3e120f36c592e71","name":"@lishenxydlgzs/aws-athena-mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@lishenxydlgzs/aws-athena-mcp","version":"1.0.0","keywords":["mcp","aws","athena","modelcontextprotocol","llm","ai"],"author":{"name":"Shen Li"},"license":"MIT","_id":"@lishenxydlgzs/aws-athena-mcp@1.0.0","maintainers":[{"name":"lishenxydlgzs","email":"lishenxydlgzs@gmail.com"}],"homepage":"https://github.com/lishenxydlgzs/aws-athena-mcp#readme","bugs":{"url":"https://github.com/lishenxydlgzs/aws-athena-mcp/issues"},"bin":{"aws-athena-mcp":"build/index.js"},"dist":{"shasum":"34bcab9cd616ba09382b87bc1bf9703f984f09c6","tarball":"https://registry.npmjs.org/@lishenxydlgzs/aws-athena-mcp/-/aws-athena-mcp-1.0.0.tgz","fileCount":9,"integrity":"sha512-RkrFYpJ6GJV0kqMx6fYQIHtdR9pL9bfKqBKXnEZyJR4WCAEYaZI24L+bWFxQi4Crj9PCClSXs2zrttCwc2SSEA==","signatures":[{"sig":"MEUCIGgqQ5xzKwaWcsx231ReOS7DPjoCGlCiaEAK4XJsJsAVAiEAs8kkj0lz+3FsO/tr0RxsLU8LaA0x+C4FSp2yadtSSI0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22413},"main":"build/index.js","type":"module","types":"build/index.d.ts","engines":{"node":">=16"},"gitHead":"dc113848189621befcc73950f065f3c93d948b6b","scripts":{"dev":"tsc -w","build":"tsc && chmod +x build/index.js","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"lishenxydlgzs","email":"lishenxydlgzs@gmail.com"},"repository":{"url":"git+https://github.com/lishenxydlgzs/aws-athena-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol (MCP) server for running AWS Athena queries","directories":{},"_nodeVersion":"20.18.2","dependencies":{"@aws-sdk/client-athena":"^3.0.0","@modelcontextprotocol/sdk":"^1.6.0","@aws-sdk/credential-provider-node":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/aws-athena-mcp_1.0.0_1740508551602_0.98549624166182","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@lishenxydlgzs/aws-athena-mcp","version":"1.0.1","description":"Model Context Protocol (MCP) server for running AWS Athena queries","type":"module","main":"build/index.js","types":"build/index.d.ts","bin":{"aws-athena-mcp":"build/index.js"},"scripts":{"build":"tsc && chmod +x build/index.js","start":"node build/index.js","dev":"tsc -w","prepublishOnly":"npm run build"},"keywords":["mcp","aws","athena","modelcontextprotocol","llm","ai"],"author":{"name":"Shen Li"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/lishenxydlgzs/aws-athena-mcp.git"},"engines":{"node":">=16"},"dependencies":{"@aws-sdk/client-athena":"^3.0.0","@aws-sdk/credential-provider-node":"^3.0.0","@modelcontextprotocol/sdk":"^1.6.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0"},"_id":"@lishenxydlgzs/aws-athena-mcp@1.0.1","gitHead":"87b702323e89c927385e45bda0dc1c3b15b33f08","bugs":{"url":"https://github.com/lishenxydlgzs/aws-athena-mcp/issues"},"homepage":"https://github.com/lishenxydlgzs/aws-athena-mcp#readme","_nodeVersion":"20.18.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-3omQT8pVEPQLB4qyaXpU63A1zKwCIbLX1NCv4A/1xUC1/tkMALMkhG5MqfQZh5U4muqeX5CFQvwNZb/Y/9qNNg==","shasum":"ce38134c5c7434835422728e9b75945d72590a53","tarball":"https://registry.npmjs.org/@lishenxydlgzs/aws-athena-mcp/-/aws-athena-mcp-1.0.1.tgz","fileCount":9,"unpackedSize":29974,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDH/CCtYQmpW3UVFI6nPi2CWjvZGsDgXPTrpx6WFdUEowIhANO5SHuChO1MAruhgyrMCVNWd68gtf99IH+A2+kpbyec"}]},"_npmUser":{"name":"lishenxydlgzs","email":"lishenxydlgzs@gmail.com"},"directories":{},"maintainers":[{"name":"lishenxydlgzs","email":"lishenxydlgzs@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aws-athena-mcp_1.0.1_1747727966676_0.43150767685679536"},"_hasShrinkwrap":false}},"time":{"created":"2025-02-25T18:35:51.495Z","modified":"2025-05-20T07:59:27.012Z","1.0.0":"2025-02-25T18:35:51.834Z","1.0.1":"2025-05-20T07:59:26.850Z"},"bugs":{"url":"https://github.com/lishenxydlgzs/aws-athena-mcp/issues"},"author":{"name":"Shen Li"},"license":"MIT","homepage":"https://github.com/lishenxydlgzs/aws-athena-mcp#readme","keywords":["mcp","aws","athena","modelcontextprotocol","llm","ai"],"repository":{"type":"git","url":"git+https://github.com/lishenxydlgzs/aws-athena-mcp.git"},"description":"Model Context Protocol (MCP) server for running AWS Athena queries","maintainers":[{"name":"lishenxydlgzs","email":"lishenxydlgzs@gmail.com"}],"readme":"# @lishenxydlgzs/aws-athena-mcp\n[![smithery badge](https://smithery.ai/badge/@lishenxydlgzs/aws-athena-mcp)](https://smithery.ai/server/@lishenxydlgzs/aws-athena-mcp)\n\nA Model Context Protocol (MCP) server for running AWS Athena queries. This server enables AI assistants to execute SQL queries against your AWS Athena databases and retrieve results.\n\n<a href=\"https://glama.ai/mcp/servers/0i7dhkex6t\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/0i7dhkex6t/badge\" alt=\"aws-athena-mcp MCP server\" />\n</a>\n\n## Usage\n\n1. Configure AWS credentials using one of the following methods:\n   - AWS CLI configuration\n   - Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)\n   - IAM role (if running on AWS)\n\n2. Add the server to your MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"athena\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@lishenxydlgzs/aws-athena-mcp\"],\n      \"env\": {\n        // Required\n        \"OUTPUT_S3_PATH\": \"s3://your-bucket/athena-results/\",\n        \n        // Optional AWS configuration\n        \"AWS_REGION\": \"us-east-1\",                    // Default: AWS CLI default region\n        \"AWS_PROFILE\": \"default\",                     // Default: 'default' profile\n        \"AWS_ACCESS_KEY_ID\": \"\",                      // Optional: AWS access key\n        \"AWS_SECRET_ACCESS_KEY\": \"\",                  // Optional: AWS secret key\n        \"AWS_SESSION_TOKEN\": \"\",                      // Optional: AWS session token\n        \n        // Optional server configuration\n        \"ATHENA_WORKGROUP\": \"default_workgroup\",      // Optional: specify the Athena WorkGroup\n        \"QUERY_TIMEOUT_MS\": \"300000\",                 // Default: 5 minutes (300000ms)\n        \"MAX_RETRIES\": \"100\",                         // Default: 100 attempts\n        \"RETRY_DELAY_MS\": \"500\"                       // Default: 500ms between retries\n      }\n    }\n  }\n}\n```\n\n3. The server provides the following tools:\n\n- `run_query`: Execute a SQL query using AWS Athena\n  - Parameters:\n    - database: The Athena database to query\n    - query: SQL query to execute\n    - maxRows: Maximum number of rows to return (default: 1000, max: 10000)\n  - Returns:\n    - If query completes within timeout: Full query results\n    - If timeout reached: Only the queryExecutionId for later retrieval\n\n- `get_status`: Check the status of a query execution\n  - Parameters:\n    - queryExecutionId: The ID returned from run_query\n  - Returns:\n    - state: Query state (QUEUED, RUNNING, SUCCEEDED, FAILED, or CANCELLED)\n    - stateChangeReason: Reason for state change (if any)\n    - submissionDateTime: When the query was submitted\n    - completionDateTime: When the query completed (if finished)\n    - statistics: Query execution statistics (if available)\n\n- `get_result`: Retrieve results for a completed query\n  - Parameters:\n    - queryExecutionId: The ID returned from run_query\n    - maxRows: Maximum number of rows to return (default: 1000, max: 10000)\n  - Returns:\n    - Full query results if the query has completed successfully\n    - Error if query failed or is still running\n\n- `list_saved_queries`: List all saved (named) queries in Athena.\n\n- Returns:\n  - An array of saved queries with `id`, `name`, and optional `description`\n  - Queries are returned from the configured `ATHENA_WORKGROUP` and `AWS_REGION`\n\n- run_saved_query: Run a previously saved query by its ID.\n- Parameters:\n  - `namedQueryId`: ID of the saved query\n  - `databaseOverride`: Optional override of the saved query's default database\n  - `maxRows`: Maximum number of rows to return (default: 1000)\n  - `timeoutMs`: Timeout in milliseconds (default: 60000)\n- Returns:\n  - Same behavior as `run_query`: full results or execution ID\n\n---\n\n## Usage Examples\n\n### Show All Databases\nMessage to AI Assistant:\n```List all databases in Athena```\n\nMCP parameter:\n```json\n{\n  \"database\": \"default\",\n  \"query\": \"SHOW DATABASES\"\n}\n```\n\n### List Tables in a Database\nMessage to AI Assistant:\n```Show me all tables in the default database```\n\nMCP parameter:\n```json\n{\n  \"database\": \"default\",\n  \"query\": \"SHOW TABLES\"\n}\n```\n\n### Get Table Schema\nMessage to AI Assistant:\n```What's the schema of the asin_sitebestimg table?```\n\nMCP parameter:\n```json\n{\n  \"database\": \"default\",\n  \"query\": \"DESCRIBE default.asin_sitebestimg\"\n}\n```\n\n### Table Rows Preview\nMessage to AI Assistant:\n```Show some rows from my_database.mytable```\n\nMCP parameter:\n```json\n{\n  \"database\": \"my_database\",\n  \"query\": \"SELECT * FROM my_table LIMIT 10\",\n  \"maxRows\": 10\n}\n```\n\n### Advanced Query with Filtering and Aggregation\nMessage to AI Assistant:\n```Find the average price by category for in-stock products```\n\nMCP parameter:\n```json\n{\n  \"database\": \"my_database\",\n  \"query\": \"SELECT category, COUNT(*) as count, AVG(price) as avg_price FROM products WHERE in_stock = true GROUP BY category ORDER BY count DESC\",\n  \"maxRows\": 100\n}\n```\n\n### Checking Query Status\n```json\n{\n  \"queryExecutionId\": \"12345-67890-abcdef\"\n}\n```\n\n### Getting Results for a Completed Query\n```json\n{\n  \"queryExecutionId\": \"12345-67890-abcdef\",\n  \"maxRows\": 10\n}\n```\n\n### Listing Saved Queries\n```json\n{\n  \"name\": \"list_saved_queries\",\n  \"arguments\": {}\n}\n```\n\n### Running a Saved Query\n```json\n{\n  \"name\": \"run_saved_query\",\n  \"arguments\": {\n    \"namedQueryId\": \"abcd-1234-efgh-5678\",\n    \"maxRows\": 100\n  }\n}\n```\n\n---\n\n## Requirements\n\n- Node.js >= 16\n- AWS credentials with appropriate Athena and S3 permissions\n- S3 bucket for query results\n- Named queries (optional) must exist in the specified `ATHENA_WORKGROUP` and `AWS_REGION`\n\n---\n\n## License\n\nMIT\n\n## Repository\n\n[GitHub Repository](https://github.com/lishenxydlgzs/aws-athena-mcp)\n","readmeFilename":"README.md"}