= poly-cloud-mcp

image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]

:toc: :toc-placement!:

image:https://img.shields.io/badge/RSR-compliant-gold[RSR Compliant,link=https://github.com/hyperpolymath/rhodium-standard-repositories] image:https://img.shields.io/badge/MCP-server-blue[MCP Server,link=https://github.com/modelcontextprotocol]

Unified MCP server for multi-cloud provider management. Provides Model Context Protocol tools for interacting with AWS, Google Cloud, Azure, and DigitalOcean through their respective CLI tools.

toc::[]

== Overview

poly-cloud-mcp exposes cloud provider management capabilities through the Model Context Protocol (MCP), enabling AI assistants and other MCP clients to manage cloud resources across multiple providers.

== Adapters

=== AWS (13 tools) Amazon Web Services via aws CLI:

• aws_s3_ls - List S3 buckets/objects
• aws_s3_cp - Copy files to/from S3
• aws_ec2_describe_instances - Describe EC2 instances
• aws_ec2_start_instances - Start EC2 instances
• aws_ec2_stop_instances - Stop EC2 instances
• aws_lambda_list - List Lambda functions
• aws_lambda_invoke - Invoke Lambda functions
• aws_iam_list_users - List IAM users
• aws_sts_get_caller_identity - Get current identity
• aws_cloudwatch_get_metrics - Get CloudWatch metrics
• aws_rds_describe_instances - Describe RDS instances
• aws_ecs_list_clusters - List ECS clusters
• aws_ecs_list_services - List ECS services

=== Google Cloud (12 tools) Google Cloud Platform via gcloud CLI:

• gcloud_compute_instances_list - List Compute Engine VMs
• gcloud_compute_instances_start - Start VMs
• gcloud_compute_instances_stop - Stop VMs
• gcloud_storage_ls - List Cloud Storage buckets/objects
• gcloud_storage_cp - Copy files to/from Cloud Storage
• gcloud_functions_list - List Cloud Functions
• gcloud_run_services_list - List Cloud Run services
• gcloud_sql_instances_list - List Cloud SQL instances
• gcloud_container_clusters_list - List GKE clusters
• gcloud_projects_list - List projects
• gcloud_config_list - Show current configuration
• gcloud_auth_list - List authenticated accounts

=== Azure (12 tools) Microsoft Azure via az CLI:

• az_vm_list - List virtual machines
• az_vm_start - Start VMs
• az_vm_stop - Stop VMs
• az_storage_account_list - List storage accounts
• az_storage_blob_list - List blobs in container
• az_webapp_list - List Web Apps
• az_functionapp_list - List Function Apps
• az_aks_list - List AKS clusters
• az_sql_server_list - List SQL servers
• az_group_list - List resource groups
• az_account_show - Show current account
• az_account_list - List subscriptions

=== DigitalOcean (13 tools) DigitalOcean via doctl CLI:

• doctl_droplet_list - List droplets
• doctl_droplet_create - Create droplets
• doctl_droplet_delete - Delete droplets
• doctl_droplet_actions - Perform droplet actions
• doctl_kubernetes_cluster_list - List K8s clusters
• doctl_kubernetes_cluster_kubeconfig - Get kubeconfig
• doctl_database_list - List managed databases
• doctl_spaces_list - List Spaces
• doctl_apps_list - List App Platform apps
• doctl_domain_list - List domains
• doctl_domain_records - List DNS records
• doctl_account_get - Get account info
• doctl_balance_get - Get account balance

== Runtime Mode

[IMPORTANT]

Local-Agent Mode Only — This MCP server wraps CLI tools (aws, gcloud, az, doctl) and requires --allow-run permission. It cannot run in Hosted-HTTP mode.

|=== |Mode |Supported |Notes

|Local-Agent (stdio) |✓ Yes |Primary mode. Runs locally, executes CLI commands.

|Hosted-HTTP |✗ No |Cannot wrap CLI tools from a hosted environment. |===

== Security Boundary

[WARNING]

This MCP server executes external CLI commands using Deno's --allow-run permission. The security boundary is your local cloud CLI configuration and credentials.

What this means:

• Commands run with your locally configured cloud credentials
• AWS: Uses ~/.aws/credentials or AWS_* environment variables
• GCP: Uses gcloud auth login or service account
• Azure: Uses az login session
• DigitalOcean: Uses doctl auth or DIGITALOCEAN_ACCESS_TOKEN
• The MCP client (e.g., Claude) can perform any CLI action your credentials allow

Recommendations:

1. Use IAM roles with minimal necessary permissions
2. Consider separate credentials for MCP access
3. Avoid running with admin/owner-level credentials
4. Review tool calls before approving in your MCP client
5. Set billing alerts for your cloud accounts

== Requirements

• https://deno.land/[Deno] runtime (v2.0+)
• https://aws.amazon.com/cli/[AWS CLI] (optional, for AWS tools)
• https://cloud.google.com/sdk/gcloud[gcloud CLI] (optional, for GCP tools)
• https://docs.microsoft.com/en-us/cli/azure/[Azure CLI] (optional, for Azure tools)
• https://docs.digitalocean.com/reference/doctl/[doctl] (optional, for DigitalOcean tools)

== Installation

[source,bash]

git clone https://github.com/hyperpolymath/poly-cloud-mcp cd poly-cloud-mcp

== Usage

Run as MCP server (Local-Agent mode):

[source,bash]

deno run --allow-run --allow-read --allow-env main.js

Or use the systemd service:

[source,bash]

systemctl --user enable poly-cloud-mcp systemctl --user start poly-cloud-mcp

== Smoke Test

Verify the server is working correctly:

[source,bash]

1. Check Deno can run the server

deno run --allow-run --allow-read --allow-env main.js & SERVER_PID=$!

2. Verify at least one CLI is accessible

aws --version || gcloud --version || az --version || doctl version

3. Test authentication (pick your provider)

aws sts get-caller-identity # AWS gcloud auth list # GCP az account show # Azure doctl account get # DigitalOcean

4. Cleanup

kill $SERVER_PID

Expected smoke test results:

|=== |Check |Expected Result

|Server starts |No errors, listens on stdio

|CLI available |At least one cloud CLI returns version

|Auth configured |CLI shows authenticated identity

|Tool call works |Returns cloud resources (if any exist) |===

== License

MIT