Athena Investigation MCP Server

一个窄范围、只读的 Model Context Protocol (MCP) 服务器，用于针对固定的 Amazon Athena 表进行受治理的调查。

该服务器有意只暴露两个面向调查的工具，而不是任意 SQL：

• search_lake_access_events 搜索精确的用户、IP 或关联指标。

• summarize_lake_access_correlation 聚合单个精确关联 ID 的操作和数据集。

这是一个参考实现，不是 AWS 或 Microsoft 的官方产品。

为什么这样设计

给 AI 代理一个通用的 execute_sql 工具会带来不必要地宽泛的能力。此服务器保持面向模型的契约足够小，同时由 AWS 继续负责授权和成本控制。

flowchart LR
    Client[MCP client] -->|Streamable HTTP + bearer| Server[Athena Investigation MCP]
    Server -->|Parameterized queries| Athena[Amazon Athena]
    Athena --> Glue[AWS Glue Data Catalog]
    Athena --> S3[(Amazon S3)]
    Server --> Provenance[Rows + query ID + bytes scanned]

MCP 是工具契约。它不能取代 AWS IAM、Athena 工作组、数据治理或 SIEM。

Related MCP server: MCP Athena Analytics Server

安全属性

• 仅发布两个只读工具。

• 这些工具从不接受 SQL 文本。

• 事件搜索至少需要一个精确指标。

• 在调用 Athena 之前，会验证指标语法和 IP 地址。

• 值通过 Athena 执行参数传递。

• 请求的结果会被限制在服务器端的最大值。

• 查询超时由服务器强制执行。

• 响应包含来源、分类、工作组、查询执行 ID、扫描字节数和结果计数。

• 缺少 MCP_API_KEY 或其长度不足 32 个字符时，HTTP 启动将失败关闭（fail closed）。

• 容器以非 root 用户运行。

这些控制措施只是其中一层。请使用专门的 AWS 主体、成本受限的 Athena 工作组、私有 S3 存储桶和经过审查的 MCP 工具白名单进行部署。

预期的 Athena 表结构

配置的表必须包含以下列：

在 examples/athena 下提供了一个合成数据示例。

快速开始

1. 准备 AWS

创建表、私有数据存储桶、私有查询结果存储桶，以及专门的 Athena 工作组。在工作组上配置扫描字节数上限。

请参阅 AWS 设置 和示例 最小权限 IAM 策略。

2. 安装

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

3. 配置

export AWS_REGION=us-east-1
export ATHENA_DATABASE=security_lake
export ATHENA_TABLE=access_events
export ATHENA_WORKGROUP=mcp-investigation
export MAX_RESULTS=20
export QUERY_TIMEOUT_SECONDS=15
export SOURCE_NAME=aws-athena
export DATA_CLASSIFICATION=synthetic
export MCP_API_KEY="$(openssl rand -hex 32)"

AWS 凭证通过标准 boto3 凭证链解析。建议优先使用通过工作负载身份或角色联合获得的临时凭证。

4. 运行

uvicorn athena_investigation_mcp.app:app \
  --host 127.0.0.1 \
  --port 8000

端点：

• MCP：http://127.0.0.1:8000/mcp

• 健康检查：http://127.0.0.1:8000/health

5. 测试

python -m pytest -q

export MCP_URL=http://127.0.0.1:8000/mcp
export MCP_TOKEN="$MCP_API_KEY"
python smoke_test.py

设置 SMOKE_CORRELATION_ID，以针对已配置的数据执行这两个工具。

容器

docker build -t athena-investigation-mcp-server .
docker run --rm -p 8000:8000 \
  -e AWS_REGION \
  -e ATHENA_DATABASE \
  -e ATHENA_TABLE \
  -e ATHENA_WORKGROUP \
  -e DATA_CLASSIFICATION \
  -e MCP_API_KEY \
  athena-investigation-mcp-server

请使用平台的工作负载身份支持，而不是将长期有效的 AWS 密钥复制到镜像中。

MCP 客户端集成

任何 Streamable HTTP MCP 客户端都可以使用以下方式连接到 /mcp：

Authorization: Bearer <MCP_API_KEY>

有关 Microsoft Copilot Studio 的说明，请参阅 Copilot Studio 设置。

配置

生产环境注意事项

内置的静态 Bearer 验证器适用于受控的参考部署。对于生产环境：

• 用你所在组织支持的 OAuth/OIDC 模式替换静态 Bearer 认证；

• 使用工作负载身份和 AWS STS 临时凭证；

• 将 IAM 资源限制在确切的工作组、目录对象和 S3 前缀范围内；

• 在工作组中强制执行扫描字节数上限和查询结果加密；

• 增加网络入口限制、WAF/API 网关控制和集中式审计日志；

• 独立于后端 IAM 审查 MCP 工具白名单；

• 将返回的源数据视为不受信任的内容；

• 将变更操作保留在独立的服务器、身份和审批流程中。

请参阅完整的 安全模型。

范围与限制

• 表结构按设计固定不变。

• 多个提供的搜索指标使用 OR 组合。

• 结果检索有意限制为单页和配置的最大值。

• 此服务器不是通用的 Athena 查询接口。

• 此服务器不摄取、检测、持续关联，也不取代 SIEM。

许可证

MIT