aws mcp

Local 2025-08-31 23:22:52 0

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your AWS environment. This allows for natural language querying and management of your AWS resources during conversations. Think of better Amazon Q alternative.

AWS MCP

Features

? Query and modify AWS resources using natural language
☁️ Support for multiple AWS profiles and SSO authentication
? Multi-region support
? Secure credential handling (no credentials are exposed to external services, your local credentials are used)
?‍♂️ Local execution with your AWS credentials

Prerequisites

Node.js
Claude Desktop
AWS credentials configured locally (~/.aws/ directory)

Installation

Clone the repository:

git clone https://github.com/RafalWilinski/aws-mcp
cd aws-mcp

Install dependencies:

pnpm install
# or
npm install

Usage

Open Claude desktop app and go to Settings -> Developer -> Edit Config

Claude Settings

Add the following entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "aws": {
      "command": "npm", // OR pnpm
      "args": [
        "--silent",
        "--prefix",
        "/Users/<YOUR USERNAME>/aws-mcp",
        "start"
      ]
    }
  }
}

Important: Replace /Users/<YOUR USERNAME>/aws-mcp with the actual path to your project directory.

Restart Claude desktop app. You should see this:

Claude MCP Connection Status

Start by selecting an AWS profile or jump to action by asking:
"List available AWS profiles"
"List all EC2 instances in my account"
"Show me S3 buckets with their sizes"
"What Lambda functions are deployed in us-east-1?"
"List all ECS clusters and their services"

Using with `nvm`

Build from source first and add following config:

{
  "mcpServers": {
    "aws": {
      "command": "/Users/<USERNAME>/.nvm/versions/node/v20.10.0/bin/node",
      "args": [
        "<WORKSPACE_PATH>/aws-mcp/node_modules/tsx/dist/cli.mjs",
        "<WORKSPACE_PATH>/aws-mcp/index.ts",
        "--prefix",
        "<WORKSPACE_PATH>/aws-mcp",
        "start"
      ]
    }
  }
}

Troubleshooting

To see logs:

tail -n 50 -f ~/Library/Logs/Claude/mcp-server-aws.log
# or
tail -n 50 -f ~/Library/Logs/Claude/mcp.log

Features in Development

MFA support
Cache SSO credentials to prevent from refreshing them too eagerly

[
  {
    "description": "Run AWS code",
    "inputSchema": {
      "properties": {
        "code": {
          "description": "Your job is to answer questions about AWS environment by writing Javascript code using AWS SDK V2. The code must be adhering to a few rules:n- Must be preferring promises over callbacksn- Think step-by-step before writing the code, approach it logicallyn- MUST written in Javascript (NodeJS) using AWS-SDK V2n- Avoid hardcoded values like ARNsn- Code written should be as parallel as possible enabling the fastest and the most optimal executionn- Code should be handling errors gracefully, especially when doing multiple SDK calls (e.g. when mapping over an array). Each error should be handled and logged with a reason, script should continue to run despite errorsn- DO NOT require or import "aws-sdk", it is already available as "AWS" variablen- Access to 3rd party libraries apart from "aws-sdk" is not allowed or possiblen- Data returned from AWS-SDK must be returned as JSON containing only the minimal amount of data that is needed to answer the question. All extra data must be filtered outn- Code MUST "return" a value: string, number, boolean or JSON object. If code does not return anything, it will be considered as FAILEDn- Whenever tool/function call fails, retry it 3 times before giving up with an improved version of the code based on the returned feedbackn- When listing resources, ensure pagination is handled correctly so that all resources are returnedn- Do not include any comments in the coden- When doing reduce, don't forget to provide an initial valuen- Try to write code that returns as few data as possible to answer without any additional processing required after the code is runn- This tool can ONLY write code that interacts with AWS. It CANNOT generate charts, tables, graphs, etc. Please use artifacts for that insteadnBe concise, professional and to the point. Do not give generic advice, always reply with detailed & contextual data sourced from the current AWS environment. Assume user always wants to proceed, do not ask for confirmation. I'll tip you $200 if you do this right.",
          "type": "string"
        },
        "profileName": {
          "description": "Name of the AWS profile to use",
          "type": "string"
        },
        "reasoning": {
          "description": "The reasoning behind the code",
          "type": "string"
        },
        "region": {
          "description": "Region to use (if not provided, us-east-1 is used)",
          "type": "string"
        }
      },
      "required": [
        "reasoning",
        "code"
      ],
      "type": "object"
    },
    "name": "run-aws-code"
  },
  {
    "description": "List all AWS credentials/configs/profiles that are configured/usable on this machine",
    "inputSchema": {
      "properties": {},
      "required": [],
      "type": "object"
    },
    "name": "list-credentials"
  },
  {
    "description": "Selects AWS profile to use for subsequent interactions. If needed, does SSO authentication",
    "inputSchema": {
      "properties": {
        "profile": {
          "description": "Name of the AWS profile to select",
          "type": "string"
        },
        "region": {
          "description": "Region to use (if not provided, us-east-1 is used)",
          "type": "string"
        }
      },
      "required": [
        "profile"
      ],
      "type": "object"
    },
    "name": "select-profile"
  }
]