AWS MCP server setup for Claude Code and Cursor

Quick answer: The AWS MCP server wraps the AWS API as MCP tools for Claude Code and Cursor. Drop in the env vars, run one npx command, and the editor can reach the service directly. Setup takes about 5 minutes, tested on mcp-server-aws@0.5.0 on April 15, 2026.

AWS hosts hundreds of services behind a single credential model. This MCP server covers the handful used in day-to-day debugging: EC2, S3, Lambda, CloudFormation, CloudWatch, and IAM. Without an MCP connection, working with AWS means flipping between the editor and the web UI - copying IDs, pasting results, losing context. The MCP server removes that loop. Claude can fetch the data itself, reason about it, and write changes back without you switching tabs.

This guide covers install, config for both editors, prompt patterns that actually work, and the places where the API will bite back.

What this server does

The server speaks MCP over stdio and wraps the standard AWS SDK. The tool surface is grouped into these sets:

• EC2: list_instances, describe_instance, list_security_groups
• S3: list_buckets, list_objects, get_object_metadata
• Lambda: list_functions, describe_function, get_function_config
• CloudFormation: list_stacks, describe_stack, get_stack_outputs
• CloudWatch: list_alarms, get_metric_statistics, list_log_groups
• IAM: list_roles, get_role_policy

Authentication uses AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION. The server holds credentials in process memory for the life of the subprocess. Nothing is written to disk by the server itself. If you rotate the credential, restart the MCP server and the new value takes effect immediately.

The server does not implement a local cache. Every tool call is a fresh round trip. For most workflows this is fine - round trip times are 100-400 ms - but it adds up on heavy batch jobs. For those, prefer the native SDK in a script.

Installing the server

The package ships on npm as mcp-server-aws. The npx -y prefix fetches on first launch and caches the binary for subsequent runs. Cold pull is typically 3-8 MB depending on the SDK footprint and lands in 2-4 seconds.

Before touching editor config, get your credentials ready:

1. Create an IAM user or, better, an IAM Identity Center session
2. Attach a read-only policy like ReadOnlyAccess plus any service-specific managed policies you need
3. Generate an access key and secret for the user, or grab a session token from SSO
4. Store the three values (key, secret, region) in your shell profile - never commit them

Keep the credential values out of any file you commit. The rest of this guide assumes they live in your shell profile or a .envrc managed by direnv.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json or a per-project .mcp.json. Add a aws entry:

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "mcp-server-aws"],
      "env": {
        "AWS_ACCESS_KEY_ID": "AKIA...",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Restart Claude Code, then run /mcp in a session to confirm AWS is attached. Call a read-only tool as a smoke test before any write operations. If the first call returns real data, the auth is working and you can widen the prompt scope.

For team projects, commit a placeholder version of .mcp.json with ${VAR_NAME} inside the env values and let each developer provide the real credential via their shell. Claude Code expands env vars when it spawns the subprocess.

Configuring for Cursor

Cursor uses the same MCP spec and reads from ~/.cursor/mcp.json. The config is identical to Claude Code:

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "mcp-server-aws"],
      "env": {
        "AWS_ACCESS_KEY_ID": "AKIA...",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Open Cursor settings, navigate to the MCP tab, and toggle the server on. Cursor spawns the subprocess lazily on the first tool call. Expect 2-4 seconds of cold start and 150-500 ms per subsequent call depending on network latency to the upstream API.

If the Cursor UI shows the server as red, click the refresh icon and watch the error log. Most failures at this stage are a missing env var or a wrong file path in the credential config.

Example prompts and workflows

A few prompts that work reliably once the server is attached:

• "List every EC2 instance in us-east-1 that is stopped and costs more than $50 a month."
• "Show the last 10 CloudWatch alarms that changed state in the last hour."
• "Describe Lambda function process-webhooks and tell me its current runtime and memory."
• "List every S3 bucket without server-side encryption enabled."
• "Get the outputs from CloudFormation stack prod-network and show the VPC ID."

The model will chain calls. An investigation flow usually runs list_stacks, then describe_stack to find outputs, then list_instances with a tag filter to map resources back. Tell Claude the region up front; AWS SDK calls default to the env var region, which is occasionally wrong for multi-region accounts.

One pattern that saves calls: narrow the scope up front. Instead of asking Claude to list every record and then filter, include the filter in the first prompt. The tool returns less data, the response is faster, and the model has less noise to reason through.

Troubleshooting

Tool call returns InvalidClientTokenId. The access key is wrong or disabled. Regenerate in IAM > Security credentials and restart the MCP server with the new value.

Tool call returns AccessDenied. The IAM policy does not grant the action. Add the missing permission (for example ec2:DescribeInstances) or switch to the managed ReadOnlyAccess policy for broad access.

Tool call returns a region-specific error. The resource lives in a different region. Pass region= in the tool call or restart the server with a new AWS_REGION value.

Results look stale. CloudWatch metrics have a 1-5 minute delay. EC2 state changes propagate within seconds but tag updates can take up to a minute. If the data looks wrong, wait a minute and retry.

MFA-protected account rejects the call. Long-lived keys on MFA-enforced accounts need a session token. Run aws sts get-session-token to get short-lived creds, then pass the token through AWS_SESSION_TOKEN.

Server fails with ENOENT. npx is not on PATH in the env the editor inherits. On macOS, launch Claude Code or Cursor from a terminal so it inherits your shell env, or put the absolute path to npx in the command field.

Subprocess keeps restarting. The MCP transport is strict about newlines on stdio. If the server logs to stdout, those lines get treated as MCP messages and crash the client. Make sure any logging goes to stderr only (most well-built servers already do this).

Alternatives

A few options if the AWS server does not fit your setup:

• gcp-mcp covers Google Cloud with a similar read surface across Compute, Storage, and Cloud Functions.
• azure-mcp targets Azure with resource group, VM, and storage introspection tools.
• kubernetes-mcp is the right pick when most of your infrastructure runs on EKS or another k8s cluster.

The MCP server pays off during incident response and debugging sessions where Claude can pull resource state, cross-reference alarms, and explain configs without a context switch to the AWS console.

Performance notes and hardening

Steady-state call latency lands in the 150-500 ms range for most tools. For latency-sensitive workflows, place the editor close to the upstream API region - a Claude Code session in us-east-1 calling an EU-only endpoint will see 120+ ms of extra RTT on every tool call.

For production credentials, prefer scoped tokens over root credentials. Most services expose fine-grained permission models; use them. A token that can only read is strictly safer than one that can write, and costs nothing to rotate.

Log review is easier if you redirect MCP subprocess stderr to a file. Most editors do this by default, but not all surface the log path. On macOS, check ~/Library/Logs/Claude/ or the Cursor equivalent.

The AWS MCP server is the right default for any workflow that already touches AWS regularly. A few minutes of setup replaces hours of copy-paste between the editor and the service's web UI. Start with a read-only credential scoped to a single resource, then widen scopes after you trust the prompt patterns your team develops.