AWS Resource MCP

AWS 계정의 실제 리소스를 읽기 전용으로 조회하기 위해 Python으로 개발된 로컬 MCP 서버입니다.

상태

9단계가 구현되었습니다. 서버는 통합 인벤토리, 보수적인 활동 분석, 명시적 진단, 경제 분석, 실제 작업 로그에서 생성된 최소 권한 IAM 정책을 결합합니다.

Related MCP server: aws-mcp-server

예상 범위

• stdio를 통한 로컬 MCP 전송.

• 기본 리전: eu-west-1.

• AWS 조회는 전적으로 읽기 전용이며 최소 권한을 따릅니다.

• 사용 가능한 도구: health_check(), listar_recursos_aws(), analizar_actividad_recursos(), diagnosticar_cobertura_aws(), analizar_riesgo_costes(), revisar_free_tier(), consultar_costes_aws().

• Cost Explorer는 정확한 요청에 대한 임시 동의를 받을 때까지 차단됩니다.

• AWS 배포 또는 CD 없음.

안정성

10단계에는 로컬 통합 테스트, 계약, 보안, 성능 및 MCP 프로토콜 테스트가 포함됩니다. 인벤토리는 또한 각 SDK 호출 전에 AWS_MCP_MAX_REQUESTS_PER_TOOL(기본값 250)을 적용합니다. 예산이 소진되면 결과를 보존하고 partial_request_budget_exhausted를 반환합니다.

지속적 통합은 각 풀 리퀘스트에서 포맷, 린트, 컴파일, 결정적 IAM 검증 및 로컬 테스트를 실행합니다. AWS 자격 증명을 구성하지 않으며 AWS 작업을 실행하지 않습니다.

Codex와 함께 사용하기

Codex가 기본 클라이언트입니다. stdio를 통해 패키지 진입점 uv run aws-resource-mcp을 사용하고, 저장소 외부에서 AWS 프로필을 구성한 다음 "eu-west-1에 어떤 리소스가 있나요?"와 같은 자연어 질문으로 시작하세요. 응답이 partial_pending_consent인 경우 Codex는 정확한 작업을 설명하고 명시적 승인을 기다려야 하며, 영구 동의를 만들지 않습니다. Codex 통합 및 데모를 참조하세요.

v0.1.0 릴리스

첫 번째 버전은 검토 준비가 되었습니다: 읽기 전용 가드, 임시 동의, Codex 통합 및 CI가 포함됩니다. 릴리스 체크리스트를 참조하여 로컬에서 확인하고 안전한 데모를 실행하세요.

개발

프로젝트는 uv와 Python 3.12 이상으로 관리됩니다.

의존성 설치

uv sync

서버 실행

uv run aws-resource-mcp

진단을 위해 모듈로도 실행할 수 있습니다:

uv run python -m aws_resource_mcp.server

서버는 stdio를 사용합니다: MCP 클라이언트가 표준 입력과 출력을 통해 메시지를 교환할 것으로 기대합니다. SDK에 포함된 도구를 사용하여 MCP Inspector로 열 수 있습니다:

uv run mcp dev src/aws_resource_mcp/server.py

테스트 실행

uv run pytest

IAM 정책 생성 및 검증

uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --check

생성은 로컬, 결정적이며 자격 증명을 사용하지 않습니다. 프로젝트는 AWS에서 역할이나 정책을 생성하거나 수정하지 않습니다. 정책은 무료 작업, 동의가 필요한 읽기, 최대 결합을 분리합니다. IAM 권한은 애플리케이션 동의를 대체하지 않습니다.

AWS 인벤토리 실행

실제 진단 전에 로컬 구성이 어떤 ID를 해석할지 확인하세요:

aws sts get-caller-identity

그런 다음 기본 리전 eu-west-1에서 인벤토리를 실행하세요:

uv run python -m aws_resource_mcp.aws.inventory

리전과 공유 프로필은 선택 사항입니다:

uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile example

프로젝트에 키가 저장되지 않습니다. Boto3는 표준 자격 증명 해석 체인을 사용합니다. AWS_PROFILE 또는 --profile을 지정하면 저장소 외부에 이미 존재해야 하는 프로필만 선택됩니다.

MCP 도구

health_check

health_check(check_aws=True)는 로컬 상태와 AWS 접근성을 분리합니다. 인수 없이 최대 한 번의 보호된 STS 호출을 수행하며, check_aws=false로 네트워크를 사용하지 않습니다. 버전, 전송, 등록된 도구 및 어댑터, 리전, 경제 정책, 청구 가능 작업 0건을 반환합니다. 상태는 다음과 같습니다:

• ok: 서버 및 구성이 유효하며, 요청 시 STS가 응답했습니다.

• degraded: 서버는 작동하지만 자격 증명이 없거나 STS에 접근할 수 없습니다.

• error: 보안 구성 또는 내부 레지스트리를 초기화할 수 없습니다.

ID는 익명화됩니다: 일반적인 보안 주체 유형과, 존재하는 경우 마스킹된 계정만 보존됩니다. 인벤토리, Resource Explorer, 어댑터, CloudTrail 또는 CloudWatch를 실행하지 않습니다.

listar_recursos_aws

리소스를 수정하지 않고 로컬 자격 증명에 사용 가능한 AWS 인벤토리를 조회합니다. 매개변수:

• region: 검색을 특정 리전으로 제한합니다. 값이 없으면 사용 가능한 전체 범위를 사용합니다.

• services: lambda, s3, ec2 또는 rds와 같은 서비스로 필터링합니다.

• include_account_id: 익명화를 용이하게 하기 위해 응답에서 계정 ID를 생략할 수 있습니다.

• resource_types: ec2:instance와 같은 동적 유형으로 필터링합니다.

• query: 텍스트 또는 이름으로 검색합니다.

• all_regions: region이 지정되지 않은 경우 활성화된 리전을 사용합니다.

• include_details: details 내에 서비스별 메타데이터를 포함합니다.

• include_cost_indicators: 실제 지출을 주장하지 않고 잠재적 비용 신호를 포함합니다.

• confirm_potentially_billable_operations: 더 이상 권한을 부여하지 않는 레거시 매개변수입니다.

• include_activity_summary: 이미 얻은 필드만 사용하여 간단한 요약을 추가합니다. CloudTrail 또는 CloudWatch를 조회하지 않습니다.

• consent_request_id, consent_action 및 approved_services: 임시적이고 제한된 요청을 재개하거나 취소합니다.

• timeout_seconds: 1~120초 사이의 구성 가능한 예산.

MCP 클라이언트가 보낸 인수 예시:

{
  "region": "eu-west-1",
  "services": ["lambda", "s3"],
  "include_account_id": false,
  "all_regions": true
}

첫 번째 호출은 허용된 작업을 통해 얻은 리소스를 반환합니다. S3, SQS 또는 SNS를 완료하는 데 청구 가능한 작업이 필요한 경우 partial_pending_consent, pending_operations 및 5분 후 만료되는 요청을 반환합니다. 명시적인 두 번째 호출까지 해당 작업을 실행하지 않습니다:

{
  "consent_request_id": "<id devuelto por la primera llamada>",
  "consent_action": "approve",
  "approved_services": ["s3"]
}

승인은 일회용이며 원래 ID와 범위에 바인딩되고 작업, 리전 및 요청을 제한합니다. 검색과 강화는 별도로 승인됩니다. 추가 페이지에는 새 요청이 필요합니다. consent_action: "cancel"은 AWS 인벤토리를 실행하지 않습니다.

상태는 complete_for_requested_scope, partial_pending_consent, partial_timeout, partial_permission_denied, partial_unavailable, consent_cancelled 및 error를 구분합니다. 빈 목록은 조회 시 서비스가 비어 있음을 의미할 뿐입니다.

resources, all_resources 및 resources_by_service는 동일한 중복 제거된 인벤토리를 나타냅니다. 각 리소스에는 id, arn, name, service, resource_type, region, account_id, state, created_at, sources, details, cost_indicators 및 activity가 포함됩니다. 이 도구는 비용을 계산하지 않고, Free Tier를 조회하지 않으며, 쓰기 작업을 수행하지 않습니다.

analizar_actividad_recursos

모든 리소스에 대해 동일한 레지스트리와 모델을 사용하여 마지막으로 알려진 신호를 분석합니다. services, regions 및 resource_ids 필터와 inactive_days, lookback_days, include_administrative_events 및 구성 가능한 제한을 허용합니다. CloudTrail 기록은 90일로 제한되며 리소스당 한 번이 아니라 리전별로 조회됩니다.

응답은 last_functional_usage_at, last_administrative_activity_at, last_configuration_change_at 및 last_state_change_at을 구분합니다. best_known_activity_at은 항상 신호 유형도 나타냅니다. 활성 상태, Describe* 조회 또는 수정 날짜는 기능적 사용으로 제시되지 않습니다.

리소스별 상태는 active, inactive_candidate, unknown, not_supported 또는 error입니다. 비활성 후보는 검토할 항목일 뿐입니다: 충분한 기간, 조회된 관련 소스, 최근 모순된 증거가 없어야 합니다. 권한 부족, 소스 부족 또는 모호한 관계는 잘못된 비활성 확신이 아닌 unknown을 생성합니다.

CloudWatch는 기능적 지표를 제공할 수 있지만 GetMetricData, GetMetricStatistics 및 ListMetrics는 잠재적으로 청구 가능한 것으로 등록되어 차단됩니다. include_paid_sources=true는 구조화된 설명만 요청합니다. 동의를 구성하지 않으며 이 단계에서 해당 작업을 실행하지 않습니다.

diagnosticar_cobertura_aws

리소스를 열거하지 않고 MCP가 실제로 조회할 수 있는 것을 설명합니다. services 및 regions 필터를 허용하고 권한, 활동 또는 경제 정책 섹션을 생략할 수 있습니다.

STS, 활성화된 리전, 기존 Resource Explorer 인덱스, 어댑터 레지스트리 및 기능, 무료 활동 소스, 차단된 작업을 확인합니다. 검사는 실행당 5개 리전, CloudTrail 샘플, CloudWatch 호출 없음으로 제한됩니다.

커버리지 상태는 available, partial, unavailable, not_configured, permission_denied, blocked_by_cost_policy, not_supported, not_checked 및 error를 구분합니다. 정책에서 허용된 것으로 선언된 작업은 입증된 IAM 권한으로 제시되지 않습니다: 진단은 이를 테스트하기 위해 서비스 인벤토리를 실행하지 않습니다.

예시:

{
  "services": ["ec2", "rds"],
  "regions": ["eu-west-1"],
  "include_activity_sources": true
}

제한 사항은 영향, MCP가 계속할 수 있는지, 권한이 부족한지, 해결에 쓰기가 필요한지, 비용이 발생할 수 있는지 나타냅니다. 진단은 제안된 작업을 수행하지 않습니다.

analizar_riesgo_costes

인벤토리 지표와 선택적으로 공통 활동 파이프라인을 사용하여 리소스의 우선순위를 지정합니다. none_detected, low, medium, high, critical 또는 unknown, 설명 가능한 점수 및 실행 불가능한 권장 사항을 반환합니다. 신호는 지출을 확인하지 않으며 none_detected는 비용이 0임을 의미하지 않습니다.

include_free_tier=true는 공식 Free Tier 데이터를 추가합니다. include_actual_cost=true는 Cost Explorer 동의만 준비합니다: 조회를 수행하지 않습니다.

revisar_free_tier

AWS가 무료로 문서화한 작업인 GetFreeTierUsage 및 GetAccountPlanState를 조회합니다. 월별 한도, 예측, 플랜 및 크레딧을 구분합니다. 권한, 업데이트 지연, 혜택 소진 또는 자격 차이로 인해 부분적이거나 알 수 없는 정보를 반환할 수 있습니다. 특정 리소스가 무료라고 주장하지 않습니다.

consultar_costes_aws

정확한 기간 및 필터에 대한 집계 GetCostAndUsage 조회를 준비합니다. 첫 번째 호출은 AWS 작업을 0회 실행하고 기본 보기에서 요청당 게시된 가격 0.01 USD로 임시 요청을 반환합니다. consent_action="approve"가 있는 두 번째 호출은 최대 한 페이지를 실행합니다. 추가 페이지마다 새 동의가 필요합니다. cancel은 AWS를 호출하지 않습니다.

세분성은 MONTHLY 또는 DAILY일 수 있습니다. end_date는 제외됩니다. 예측, 리소스별 세부 정보, 연결된 계정 및 사용자 지정 결제 보기는 이 단계에서 구현되지 않습니다.

AWS 인벤토리

Boto3는 Python용 공식 AWS SDK입니다. 인벤토리 계층은 다음을 사용합니다:

• 계정 및 유효 ID를 식별하기 위한 STS GetCallerIdentity.

• 활성화된 리전만 검색하기 위한 EC2 DescribeRegions.

• 기존 인덱스 및 보기를 통해 리소스와 지원 유형을 동적으로 검색하기 위한 Resource Explorer.

• Lambda, S3, EC2/EBS/VPC, RDS/Aurora, DynamoDB, ECS/Fargate, API Gateway, CloudFormation, SQS, SNS, IAM, CloudFront 및 Route 53용 공통 어댑터 레지스트리.

• 지난 90일간의 무료 리전별 관리 이벤트 기록을 위한 CloudTrail LookupEvents.

Lambda와 S3는 처음 구현된 서비스였지만 더 이상 특별한 아키텍처 경로를 유지하지 않습니다. 모든 어댑터는 동일한 계약을 통해 메타데이터, Boto3 작업, 범위, 유형, 세부 정보 및 지표를 선언합니다. 특정 세부 정보는 details 내에만 있습니다.

결과는 ARN 또는, 없는 경우 유형, 리전 및 식별자/이름으로 중복 제거됩니다. 집계 인덱스가 선호됩니다. 로컬 인덱스가 있으면 결과가 결합되고 커버리지는 부분적입니다. Resource Explorer를 사용할 수 없으면 검색을 지원하는 선택된 모든 어댑터가 실행됩니다.

자격 증명이 없거나 계정을 식별할 수 없는 경우는 인벤토리에 대한 전역 오류지만, 로컬 상태에 대해서는 degraded 상태일 뿐입니다. 진단은 로컬 검사를 유지하고 AWS에 의존하는 검사는 안전하게 생략합니다.

모든 Boto3 호출은 먼저 중앙 레지스트리를 거칩니다. 등록되지 않은 작업, 쓰기 작업 또는 비용을 알 수 없는 작업은 차단됩니다. free-only 모드는 전체 프로세스 동안 활성 상태를 유지합니다. S3, SQS 및 SNS는 요청을 계산할 수 있습니다. 해당 열거는 보류 중으로 표시되며 정확한 임시 grant만 실행할 수 있습니다. 가드는 고유 작업과 실제 요청을 별도로 계산합니다.

MCP 클라이언트의 예: "내 계정에 어떤 리소스가 있나요?", "eu-west-1의 EC2 인스턴스를 나열해 줘", "web이라는 리소스를 검색해 줘" 또는 "배포된 RDS 유형을 보여 줘". Resource Explorer는 광범위한 범위를 제공하지만 보편적이지는 않습니다.

문서

• 아키텍처

• 결정 사항

• 단계

• 진행 상황

• 제로 비용 정책

• 서비스 어댑터

• 활동 분석

• 진단 및 범위

• 인벤토리 동의 흐름

• 경제 분석, Free Tier 및 실제 비용

• 최소 권한 IAM

• IAM 권한 매트릭스

• 수동 IAM 구성