AWS Resource MCP

Lokaler MCP-Server, entwickelt in Python, zum Abfragen realer Ressourcen eines AWS-Kontos im Nur-Lese-Modus.

Status

Phase 9 ist implementiert. Der Server kombiniert einheitliches Inventar, konservative Aktivitätsanalyse, explizite Diagnose, Kostenanalyse und IAM-Richtlinien mit minimalen Rechten, die aus dem tatsächlichen Operationsprotokoll generiert werden.

Related MCP server: aws-mcp-server

Vorgesehener Umfang

• Lokaler MCP-Transport über stdio.

• Hauptregion: eu-west-1.

• AWS-Abfragen ausschließlich lesend und mit minimalen Rechten.

• Verfügbare Tools: health_check(), listar_recursos_aws(), analizar_actividad_recursos(), diagnosticar_cobertura_aws(), analizar_riesgo_costes(), revisar_free_tier() und consultar_costes_aws().

• Cost Explorer ist blockiert, bis eine flüchtige Zustimmung für eine exakte Anfrage vorliegt.

• Kein Deployment in AWS und keine CD.

Zuverlässigkeit

Phase 10 umfasst lokale Integrations-, Vertrags-, Sicherheits-, Leistungs- und MCP-Protokolltests. Das Inventar wendet außerdem AWS_MCP_MAX_REQUESTS_PER_TOOL (standardmäßig 250) vor jedem SDK-Aufruf an; wenn das Budget erschöpft ist, behält es das Ergebnis und gibt partial_request_budget_exhausted zurück.

Die kontinuierliche Integration führt bei jedem Pull Request Formatierung, Lint, Kompilierung, deterministische IAM-Validierung und lokale Tests aus. Sie konfiguriert keine AWS-Anmeldedaten und führt keine AWS-Operationen aus.

Using with Codex

Codex is the primary client. Use the package entry point uv run aws-resource-mcp over stdio, configure any AWS profile outside the repository, and begin with natural-language questions such as “What resources do I have in eu-west-1?”. When a response is partial_pending_consent, Codex must explain the exact operation and wait for explicit approval; it never creates persistent consent. See Codex integration and the demo.

Release v0.1.0

Die erste Version ist bereit zur Überprüfung: Sie enthält den Nur-Lese-Schutz, flüchtige Zustimmung, Codex-Integration und CI. Siehe die Release-Checkliste, um sie lokal zu verifizieren und die sichere Demo auszuführen.

Entwicklung

Das Projekt wird mit uv und Python 3.12 oder neuer verwaltet.

Abhängigkeiten installieren

uv sync

Server ausführen

uv run aws-resource-mcp

Zur Diagnose kann es auch als Modul ausgeführt werden:

uv run python -m aws_resource_mcp.server

Der Server verwendet stdio: Er erwartet, dass ein MCP-Client Nachrichten über die Standardeingabe und -ausgabe austauscht. Er kann mit MCP Inspector über die im SDK enthaltenen Werkzeuge geöffnet werden:

uv run mcp dev src/aws_resource_mcp/server.py

Tests ausführen

uv run pytest

IAM-Richtlinien generieren und validieren

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

Die Generierung ist lokal, deterministisch und verwendet keine Anmeldedaten. Das Projekt erstellt oder ändert keine Rollen oder Richtlinien in AWS. Die Richtlinien trennen kostenlose Operationen, Lesezugriffe, die Zustimmung erfordern, und das maximale kombinierte Kontingent; die IAM-Berechtigung ersetzt niemals die Zustimmung der Anwendung.

AWS-Inventar ausführen

Prüfe vor der eigentlichen Diagnose, welche Identität die lokale Konfiguration auflöst:

aws sts get-caller-identity

Führe danach das Inventar in der Standardregion eu-west-1 aus:

uv run python -m aws_resource_mcp.aws.inventory

Region und gemeinsames Profil sind optional:

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

Im Projekt werden keine Schlüssel gespeichert. Boto3 verwendet seine Standardkette zur Auflösung von Anmeldedaten; wenn AWS_PROFILE oder --profile angegeben wird, wird lediglich ein Profil ausgewählt, das bereits außerhalb des Repositorys existieren muss.

MCP-Tools

health_check

health_check(check_aws=True) trennt die lokale Gesundheit von der Erreichbarkeit von AWS. Ohne Argumente führt es höchstens einen geschützten STS-Aufruf aus; mit check_aws=false verwendet es kein Netzwerk. Es gibt Version, Transport, registrierte Tools und Adapter, Region, Kostenrichtlinie und null abrechenbare Operationen zurück. Seine Status sind:

• ok: Server und Konfiguration gültig; STS hat geantwortet, als es angefordert wurde.

• degraded: Der Server funktioniert, aber es fehlen Anmeldedaten oder STS ist nicht erreichbar.

• error: Die sichere Konfiguration oder die internen Protokolle können nicht initialisiert werden.

Die Identität wird anonymisiert: Es wird nur der allgemeine Principal-Typ und, falls vorhanden, ein maskiertes Konto beibehalten. Es führt kein Inventar, keinen Resource Explorer, keine Adapter, kein CloudTrail und kein CloudWatch aus.

listar_recursos_aws

Fragt das verfügbare AWS-Inventar für die lokalen Anmeldedaten ab, ohne Ressourcen zu verändern. Parameter:

• region: Begrenzt die Suche auf eine Region; ohne Wert wird die gesamte verfügbare Abdeckung verwendet.

• services: Filtert nach Diensten wie lambda, s3, ec2 oder rds.

• include_account_id: Ermöglicht das Weglassen der Kontonummer aus der Antwort, um deren Anonymisierung zu erleichtern.

• resource_types: Filtert nach dynamischen Typen wie ec2:instance.

• query: Sucht nach Text oder Name.

• all_regions: Verwendet die aktivierten Regionen, wenn region nicht angegeben ist.

• include_details: Enthält dienstspezifische Metadaten innerhalb von details.

• include_cost_indicators: Enthält potenzielle Kostensignale, ohne tatsächliche Ausgaben zu behaupten.

• confirm_potentially_billable_operations: Geerbter Parameter, der keine Berechtigungen mehr gewährt.

• include_activity_summary: Fügt eine kurze Zusammenfassung hinzu, die nur bereits abgerufene Felder verwendet; fragt weder CloudTrail noch CloudWatch ab.

• consent_request_id, consent_action und approved_services: Setzen eine flüchtige und begrenzte Anfrage fort oder brechen sie ab.

• timeout_seconds: Konfigurierbares Budget zwischen 1 und 120 Sekunden.

Beispiel für Argumente, die von einem MCP-Client gesendet werden:

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

Der erste Aufruf gibt die Ressourcen zurück, die über zulässige Operationen abgerufen wurden. Wenn zum Abschließen von S3, SQS oder SNS abrechenbare Operationen erforderlich sind, gibt er partial_pending_consent, pending_operations und eine Anfrage zurück, die in fünf Minuten abläuft. Er führt diese Operationen erst bei einem zweiten expliziten Aufruf aus:

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

Die Genehmigung ist einmalig, an die ursprüngliche Identität und den ursprünglichen Umfang gebunden und begrenzt Operationen, Regionen und Anfragen. Entdeckung und Anreicherung werden getrennt autorisiert; eine zusätzliche Seite erfordert eine neue Anfrage. consent_action: "cancel" führt kein AWS-Inventar aus.

Die Status unterscheiden complete_for_requested_scope, partial_pending_consent, partial_timeout, partial_permission_denied, partial_unavailable, consent_cancelled und error. Eine leere Liste bedeutet nur, dass der Dienst zum Zeitpunkt der Abfrage leer war.

resources, all_resources und resources_by_service stellen dasselbe deduplizierte Inventar dar. Jede Ressource enthält id, arn, name, service, resource_type, region, account_id, state, created_at, sources, details, cost_indicators und activity. Das Tool berechnet keine Kosten, fragt kein Free Tier ab und führt keine Schreiboperationen aus.

analizar_actividad_recursos

Analysiert den letzten bekannten Hinweis über dasselbe Protokoll und Modell für alle Ressourcen. Es akzeptiert Filter nach services, regions und resource_ids sowie inactive_days, lookback_days, include_administrative_events und konfigurierbare Grenzen. Der CloudTrail-Verlauf ist auf 90 Tage begrenzt und wird pro Region abgefragt, nicht einmal pro Ressource.

Die Antwort trennt last_functional_usage_at, last_administrative_activity_at, last_configuration_change_at und last_state_change_at. best_known_activity_at gibt immer auch den Signaltyp an. Ein aktiver Status, eine Describe*-Abfrage oder ein Änderungsdatum werden nicht als funktionale Nutzung dargestellt.

Die Status pro Ressource sind active, inactive_candidate, unknown, not_supported oder error. Ein inaktiver Kandidat ist lediglich ein Element zur Überprüfung: Er erfordert ausreichendes Alter, eine relevante abgefragte Quelle und das Fehlen widersprüchlicher aktueller Belege. Fehlende Berechtigungen, unzureichende Quellen oder mehrdeutige Beziehungen ergeben unknown, keine falsche Gewissheit der Inaktivität.

CloudWatch könnte funktionale Metriken liefern, aber GetMetricData, GetMetricStatistics und ListMetrics sind als potenziell abrechenbar registriert und blockiert. include_paid_sources=true fordert nur die strukturierte Erklärung an; es stellt keine Zustimmung dar und führt diese Operationen in dieser Phase niemals aus.

diagnosticar_cobertura_aws

Erklärt, was der MCP tatsächlich abfragen kann, ohne Ressourcen aufzulisten. Es akzeptiert Filter services und regions und ermöglicht das Weglassen der Abschnitte zu Berechtigungen, Aktivität oder Kostenrichtlinie.

Es prüft STS, aktivierte Regionen, vorhandene Resource-Explorer-Indizes, Protokollierung und Fähigkeiten der Adapter, kostenlose Aktivitätsquellen und blockierte Operationen. Die Prüfungen sind auf fünf Regionen pro Ausführung, eine CloudTrail-Stichprobe und keinen CloudWatch-Aufruf begrenzt.

Die Abdeckungsstatus unterscheiden available, partial, unavailable, not_configured, permission_denied, blocked_by_cost_policy, not_supported, not_checked und error. Eine als durch die Richtlinie zulässig deklarierte Operation wird nicht als nachgewiesene IAM-Berechtigung dargestellt: Die Diagnose führt keine Dienstinventare aus, um dies zu testen.

Beispiel:

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

Die Einschränkungen geben die Auswirkung an, ob der MCP fortfahren kann, ob Berechtigungen fehlen, ob deren Behebung Schreibzugriff erfordern würde und ob Kosten entstehen könnten. Die Diagnose führt die vorgeschlagene Aktion niemals aus.

analizar_riesgo_costes

Priorisiert Ressourcen anhand der Inventarindikatoren und optional der gemeinsamen Aktivitätspipeline. Es gibt none_detected, low, medium, high, critical oder unknown, eine erklärbare Bewertung und nicht ausführbare Empfehlungen zurück. Ein Signal bestätigt keine Ausgaben und none_detected bedeutet keine Kosten von null.

include_free_tier=true fügt offizielle Free-Tier-Daten hinzu. include_actual_cost=true bereitet nur eine Cost-Explorer-Zustimmung vor: Es führt die Abfrage nicht aus.

revisar_free_tier

Fragt GetFreeTierUsage und GetAccountPlanState ab, Operationen, die AWS als kostenlos dokumentiert. Es trennt monatliche Grenzen, Prognose, Plan und Guthaben. Es kann partielle oder unbekannte Informationen zurückgeben, aufgrund von Berechtigungen, Aktualisierungsverzögerung, Erschöpfung eines Angebots oder Unterschieden bei der Berechtigung. Es behauptet nicht, dass eine bestimmte Ressource kostenlos ist.

consultar_costes_aws

Bereitet eine aggregierte GetCostAndUsage-Abfrage für einen genauen Zeitraum und genaue Filter vor. Der erste Aufruf führt null AWS-Operationen aus und gibt eine flüchtige Anfrage mit dem veröffentlichten Preis von 0,01 USD pro Anfrage auf der Hauptansicht zurück. Ein zweiter Aufruf mit consent_action="approve" führt höchstens eine Seite aus; jede zusätzliche Seite erfordert eine neue Zustimmung. cancel ruft AWS nicht auf.

Die Granularität kann MONTHLY oder DAILY sein; end_date ist exklusiv. Forecast, Details pro Ressource, verknüpfte Konten und benutzerdefinierte Billing-Ansichten sind in dieser Phase nicht implementiert.

AWS-Inventar

Boto3 ist das offizielle AWS-SDK für Python. Die Inventarebene verwendet:

• STS GetCallerIdentity zur Identifizierung des Kontos und der effektiven Identität.

• EC2 DescribeRegions, um ausschließlich aktivierte Regionen zu entdecken.

• Resource Explorer, um Ressourcen und unterstützte Typen dynamisch über vorhandene Indizes und Ansichten zu entdecken.

• Ein gemeinsames Adapterregister für Lambda, S3, EC2/EBS/VPC, RDS/Aurora, DynamoDB, ECS/Fargate, API Gateway, CloudFormation, SQS, SNS, IAM, CloudFront und Route 53.

• CloudTrail LookupEvents für den kostenlosen regionalen Verlauf der Verwaltungsereignisse der letzten 90 Tage.

Lambda und S3 waren die ersten implementierten Dienste, behalten aber keine besonderen Architekturpfade mehr. Alle Adapter deklarieren Metadaten, Boto3-Operationen, Umfang, Typen, Details und Indikatoren über denselben Vertrag. Die besonderen Details leben ausschließlich innerhalb von details.

Die Ergebnisse werden nach ARN oder, falls dieser fehlt, nach Typ, Region und Kennung/Name dedupliziert. Ein aggregierender Index wird bevorzugt; bei lokalen Indizes werden Ergebnisse kombiniert und die Abdeckung ist teilweise. Wenn Resource Explorer nicht verfügbar ist, werden alle ausgewählten Adapter ausgeführt, die Entdeckung unterstützen.

Das Fehlen von Anmeldeinformationen oder die Unmöglichkeit, das Konto zu identifizieren, ist ein globaler Fehler für das Inventar, aber nur ein degraded-Status für die lokale Gesundheit. Die Diagnose behält ihre lokalen Prüfungen bei und überspringt sicher die von AWS abhängigen.

Alle Boto3-Aufrufe durchlaufen zuerst ein zentrales Register. Nicht registrierte, Schreib- oder unbekannte Kostenoperationen werden blockiert. Der Modus free-only bleibt während des gesamten Prozesses aktiv. S3, SQS und SNS können Anfragen abrechnen: Ihre Aufzählungen werden als ausstehend dargestellt und nur ein exaktes kurzlebiges Grant ermöglicht ihre Ausführung. Der Guard zählt getrennt eindeutige Operationen und tatsächliche Anfragen.

Beispiele für einen MCP-Client: „Welche Ressourcen gibt es in meinem Konto?“, „Liste die EC2-Instanzen in eu-west-1 auf“, „Suche nach Ressourcen namens web“ oder „Zeig mir die bereitgestellten RDS-Typen“. Resource Explorer bietet eine breite, aber nicht universelle Abdeckung.

Dokumentation

• Architektur

• Entscheidungen

• Phasen

• Fortschritt

• Zero-Cost-Richtlinie

• Dienstadapter

• Aktivitätsanalyse

• Diagnose und Abdeckung

• Inventar-Zustimmungsfluss

• Wirtschaftliche Analyse, Free Tier und reale Kosten

• IAM mit minimalen Rechten

• IAM-Berechtigungsmatrix

• Manuelle IAM-Konfiguration