Skip to main content

AWS IAM MCP Server

AWS IAM MCP Server

A Model Context Protocol (MCP) server for comprehensive AWS Identity and Access Management (IAM) operations. This server provides AI assistants with the ability to manage IAM users, roles, policies, and permissions while following security best practices.

Features​

Core IAM Management​

  • User Management: Create, list, retrieve, and delete IAM users
  • Role Management: Create, list, and manage IAM roles with trust policies
  • Group Management: Create, list, retrieve, and delete IAM groups with member management
  • Policy Management: List and manage IAM policies (managed and inline)
  • Inline Policy Management: Full CRUD operations for user and role inline policies
  • Permission Management: Attach/detach policies to users and roles
  • Access Key Management: Create and delete access keys for users
  • Security Simulation: Test policy permissions before applying them

Security Features​

  • Policy Simulation: Test permissions without making changes
  • Force Delete: Safely remove users with all associated resources
  • Permissions Boundary Support: Set permission boundaries for enhanced security
  • Trust Policy Validation: Validate JSON trust policies for roles
  • Read-Only Mode: Run server in read-only mode to prevent any modifications

Best Practices Integration​

  • Follows AWS IAM security best practices
  • Supports principle of least privilege
  • Provides warnings for sensitive operations
  • Includes comprehensive error handling

Installation​

# Install using uv (recommended)
uv tool install awslabs.iam-mcp-server

# Or install using pip
pip install awslabs.iam-mcp-server

Configuration​

AWS Credentials​

The server requires AWS credentials to be configured. You can use any of the following methods:

  1. AWS Profile (recommended):

    export AWS_PROFILE=your-profile-name

  2. Environment Variables:

    export AWS_ACCESS_KEY_ID=your-access-key
    export AWS_SECRET_ACCESS_KEY=your-secret-key
    export AWS_REGION=us-east-1

  3. IAM Roles (for EC2/Lambda): The server will automatically use IAM roles when running on AWS services.

Required IAM Permissions​

The AWS credentials used by this server need the following IAM permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListUsers",
                "iam:GetUser",
                "iam:CreateUser",
                "iam:DeleteUser",
                "iam:ListRoles",
                "iam:GetRole",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:ListGroups",
                "iam:GetGroup",
                "iam:CreateGroup",
                "iam:DeleteGroup",
                "iam:AddUserToGroup",
                "iam:RemoveUserFromGroup",
                "iam:AttachGroupPolicy",
                "iam:DetachGroupPolicy",
                "iam:ListAttachedGroupPolicies",
                "iam:ListGroupPolicies",
                "iam:ListPolicies",
                "iam:GetPolicy",
                "iam:CreatePolicy",
                "iam:DeletePolicy",
                "iam:AttachUserPolicy",
                "iam:DetachUserPolicy",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:ListAttachedUserPolicies",
                "iam:ListAttachedRolePolicies",
                "iam:ListUserPolicies",
                "iam:ListRolePolicies",
                "iam:GetUserPolicy",
                "iam:GetRolePolicy",
                "iam:PutUserPolicy",
                "iam:PutRolePolicy",
                "iam:GetGroupsForUser",
                "iam:ListAccessKeys",
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:SimulatePrincipalPolicy",
                "iam:RemoveUserFromGroup",
                "iam:DeleteUserPolicy",
                "iam:DeleteRolePolicy"
            ],
            "Resource": "*"
        }
    ]
}

MCP Client Configuration​

Amazon Q CLI​

Add to your ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "awslabs.iam-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.iam-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Cline​

Add to your cline_mcp_settings.json:

{
  "mcpServers": {
    "awslabs.iam-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.iam-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Cursor​

Install in Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "awslabs.iam-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.iam-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Read-Only Mode​

The server supports a read-only mode that prevents all mutating operations while still allowing read operations. This is useful for:

  • Safety: Preventing accidental modifications in production environments
  • Testing: Allowing safe exploration of IAM resources without risk of changes
  • Auditing: Running the server in environments where only read access should be allowed

Enabling Read-Only Mode​

Add the --readonly flag when starting the server:

# Using uvx
uvx awslabs.iam-mcp-server@latest --readonly

# Or if installed locally
python -m awslabs.iam_mcp_server.server --readonly

MCP Client Configuration with Read-Only Mode​

Amazon Q CLI​

{
  "mcpServers": {
    "awslabs.iam-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.iam-mcp-server@latest", "--readonly"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Other MCP Clients​

Simply add "--readonly" to the args array in your MCP configuration.

Operations Blocked in Read-Only Mode​

When read-only mode is enabled, the following operations will return an error:

  • create_user
  • delete_user
  • create_role
  • attach_user_policy
  • detach_user_policy
  • create_access_key
  • delete_access_key

Operations Available in Read-Only Mode​

These operations continue to work normally:

  • list_users
  • get_user
  • list_roles
  • list_policies
  • simulate_principal_policy

Available Tools​

User Management​

list_users​

List IAM users in the account with optional filtering.

Parameters:

  • path_prefix (optional): Path prefix to filter users (e.g., "/division_abc/")
  • max_items (optional): Maximum number of users to return (default: 100)

get_user​

Get detailed information about a specific IAM user including attached policies, groups, and access keys.

Parameters:

  • user_name: The name of the IAM user to retrieve

create_user​

Create a new IAM user.

Parameters:

  • user_name: The name of the new IAM user
  • path (optional): The path for the user (default: "/")
  • permissions_boundary (optional): ARN of the permissions boundary policy

delete_user​

Delete an IAM user with optional force cleanup.

Parameters:

  • user_name: The name of the IAM user to delete
  • force (optional): Force delete by removing all attached resources first (default: false)

Role Management​

list_roles​

List IAM roles in the account with optional filtering.

Parameters:

  • path_prefix (optional): Path prefix to filter roles (e.g., "/service-role/")
  • max_items (optional): Maximum number of roles to return (default: 100)

create_role​

Create a new IAM role with a trust policy.

Parameters:

  • role_name: The name of the new IAM role
  • assume_role_policy_document: The trust policy document in JSON format
  • path (optional): The path for the role (default: "/")
  • description (optional): Description of the role
  • max_session_duration (optional): Maximum session duration in seconds (default: 3600)
  • permissions_boundary (optional): ARN of the permissions boundary policy

Group Management​

list_groups​

List IAM groups in the account with optional filtering.

Parameters:

  • path_prefix (optional): Path prefix to filter groups (e.g., "/division_abc/")
  • max_items (optional): Maximum number of groups to return (default: 100)

get_group​

Get detailed information about a specific IAM group including members, attached policies, and inline policies.

Parameters:

  • group_name: The name of the IAM group to retrieve

create_group​

Create a new IAM group.

Parameters:

  • group_name: The name of the new IAM group
  • path (optional): The path for the group (default: "/")

delete_group​

Delete an IAM group with optional force cleanup.

Parameters:

  • group_name: The name of the IAM group to delete
  • force (optional): Force delete by removing all members and policies first (default: false)

add_user_to_group​

Add a user to an IAM group.

Parameters:

  • group_name: The name of the IAM group
  • user_name: The name of the IAM user

remove_user_from_group​

Remove a user from an IAM group.

Parameters:

  • group_name: The name of the IAM group
  • user_name: The name of the IAM user

attach_group_policy​

Attach a managed policy to an IAM group.

Parameters:

  • group_name: The name of the IAM group
  • policy_arn: The ARN of the policy to attach

detach_group_policy​

Detach a managed policy from an IAM group.

Parameters:

  • group_name: The name of the IAM group
  • policy_arn: The ARN of the policy to detach

Policy Management​

list_policies​

List IAM policies in the account.

Parameters:

  • scope (optional): Scope of policies to list: "All", "AWS", or "Local" (default: "Local")
  • only_attached (optional): Only return policies that are attached (default: false)
  • path_prefix (optional): Path prefix to filter policies
  • max_items (optional): Maximum number of policies to return (default: 100)

attach_user_policy​

Attach a managed policy to an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • policy_arn: The ARN of the policy to attach

detach_user_policy​

Detach a managed policy from an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • policy_arn: The ARN of the policy to detach

Access Key Management​

create_access_key​

Create a new access key for an IAM user.

Parameters:

  • user_name: The name of the IAM user

⚠️ Security Warning: The secret access key is only returned once and cannot be retrieved again.

delete_access_key​

Delete an access key for an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • access_key_id: The access key ID to delete

Security Analysis​

simulate_principal_policy​

Simulate IAM policy evaluation for a principal to test permissions.

Parameters:

  • policy_source_arn: ARN of the user or role to simulate
  • action_names: List of actions to simulate
  • resource_arns (optional): List of resource ARNs to test against
  • context_entries (optional): Context entries for the simulation

Inline Policy Management​

put_user_policy​

Create or update an inline policy for an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • policy_name: The name of the inline policy
  • policy_document: The policy document in JSON format (string or dict)

get_user_policy​

Retrieve an inline policy for an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • policy_name: The name of the inline policy

delete_user_policy​

Delete an inline policy from an IAM user.

Parameters:

  • user_name: The name of the IAM user
  • policy_name: The name of the inline policy to delete

list_user_policies​

List all inline policies for an IAM user.

Parameters:

  • user_name: The name of the IAM user

put_role_policy​

Create or update an inline policy for an IAM role.

Parameters:

  • role_name: The name of the IAM role
  • policy_name: The name of the inline policy
  • policy_document: The policy document in JSON format (string or dict)

get_role_policy​

Retrieve an inline policy for an IAM role.

Parameters:

  • role_name: The name of the IAM role
  • policy_name: The name of the inline policy

delete_role_policy​

Delete an inline policy from an IAM role.

Parameters:

  • role_name: The name of the IAM role
  • policy_name: The name of the inline policy to delete

list_role_policies​

List all inline policies for an IAM role.

Parameters:

  • role_name: The name of the IAM role

Usage Examples​

Basic User Management​

# List all users
users = await list_users()

# Get specific user details
user_details = await get_user(user_name="john.doe")

# Create a new user
new_user = await create_user(
    user_name="jane.smith",
    path="/developers/"
)

# Delete a user (with force cleanup)
await delete_user(user_name="old.user", force=True)

Role Management​

# Create a role for EC2 instances
trust_policy = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {"Service": "ec2.amazonaws.com"},
            "Action": "sts:AssumeRole"
        }
    ]
}

role = await create_role(
    role_name="EC2-S3-Access-Role",
    assume_role_policy_document=json.dumps(trust_policy),
    description="Role for EC2 instances to access S3"
)

Group Management​

# Create a new group
group = await create_group(
    group_name="Developers",
    path="/teams/"
)

# Add users to the group
await add_user_to_group(
    group_name="Developers",
    user_name="john.doe"
)

# Attach a policy to the group
await attach_group_policy(
    group_name="Developers",
    policy_arn="arn:aws:iam::123456789012:policy/DeveloperPolicy"
)

# Get group details including members
group_details = await get_group(group_name="Developers")

Policy Management​

# List customer managed policies
policies = await list_policies(scope="Local", only_attached=True)

# Attach a policy to a user
await attach_user_policy(
    user_name="developer",
    policy_arn="arn:aws:iam::123456789012:policy/DeveloperPolicy"
)

Security Testing​

# Test if a user can perform specific actions
simulation = await simulate_principal_policy(
    policy_source_arn="arn:aws:iam::123456789012:user/developer",
    action_names=["s3:GetObject", "s3:PutObject"],
    resource_arns=["arn:aws:s3:::my-bucket/*"]
)

Inline Policy Management​

# Create an inline policy for a user
policy_document = {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:GetObject", "s3:PutObject"],
            "Resource": "arn:aws:s3:::my-bucket/*"
        }
    ]
}

await put_user_policy(
    user_name="developer",
    policy_name="S3AccessPolicy",
    policy_document=policy_document
)

# Retrieve an inline policy
policy = await get_user_policy(
    user_name="developer",
    policy_name="S3AccessPolicy"
)

# List all inline policies for a user
policies = await list_user_policies(user_name="developer")

# Create an inline policy for a role
await put_role_policy(
    role_name="EC2-S3-Access-Role",
    policy_name="S3ReadOnlyPolicy",
    policy_document={
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "s3:GetObject",
                "Resource": "*"
            }
        ]
    }
)

# Delete an inline policy
await delete_user_policy(
    user_name="developer",
    policy_name="S3AccessPolicy"
)

Security Best Practices​

  1. Principle of Least Privilege: Always grant the minimum permissions necessary
  2. Use Roles for Applications: Prefer IAM roles over users for applications
  3. Regular Access Reviews: Periodically review and clean up unused users and permissions
  4. Access Key Rotation: Regularly rotate access keys
  5. Enable MFA: Use multi-factor authentication where possible
  6. Permissions Boundaries: Use permissions boundaries to set maximum permissions
  7. Policy Simulation: Test policies before applying them to production
  8. Prefer Managed Policies: Use managed policies over inline policies for reusable permissions
  9. Inline Policy Guidelines: Use inline policies only for permissions unique to a single identity

Error Handling​

The server provides comprehensive error handling with descriptive messages:

  • Authentication Errors: Clear messages for credential issues
  • Permission Errors: Specific information about missing permissions
  • Resource Not Found: Helpful messages when resources don't exist
  • Validation Errors: Detailed feedback on invalid parameters

Development​

Running Tests​

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=awslabs.iam_mcp_server

Local Development​

# Install in development mode
uv pip install -e .

# Run the server directly
python -m awslabs.iam_mcp_server.server

Contributing​

Contributions are welcome! Please see the main repository's CONTRIBUTING.md for guidelines.

License​

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support​

For issues and questions:

  1. Check the AWS IAM documentation
  2. Review the MCP specification
  3. Open an issue in the GitHub repository

Changelog​

See CHANGELOG.md for version history and changes.