use_aws_mcp

What is use_aws_mcp?

use_aws_mcp is a standalone Model Context Protocol (MCP) server that extracts and provides the AWS CLI interaction functionality, originally found in the use_aws tool of the Amazon Q Developer CLI, as an independent and portable service. This allows other AI tools and MCP clients to interact with AWS APIs seamlessly.

How to use use_aws_mcp?

To use use_aws_mcp, you first need to install it using Cargo: cargo install use_aws_mcp. Then, configure your MCP client with the provided JSON configuration, specifying the command and other parameters. Ensure you have Rust, Cargo, AWS CLI, and AWS credentials configured. For non-shell MCP clients, it is recommended to explicitly set the AWS profile. You can also run the MCP server locally via ./target/release/use_aws_mcp.

Key Features of use_aws_mcp

• AWS CLI Integration: Execute AWS CLI commands with proper parameter handling.
• Safety Checks: Automatic detection of read-only vs. write operations, requiring user acceptance for write operations.
• User Agent Management: Proper AWS CLI user agent setup for tracking.
• Parameter Formatting: Automatic conversion of parameters to kebab-case for CLI compatibility.
• Error Handling: Comprehensive error handling and output formatting.
• MCP Protocol: Full Model Context Protocol compliance.
• Human-Readable Descriptions: Rich command descriptions using terminal formatting.
• Output Truncation: Large outputs are automatically truncated to prevent memory issues.

Use Cases of use_aws_mcp

use_aws_mcp is designed for AI tools and MCP clients that need to interact with AWS APIs. Specific use cases include:

• Integrating AWS CLI functionality into various AI tools: Allows AI tools to programmatically execute AWS commands.
• Automating AWS tasks: Enables AI-driven automation of cloud operations.
• Providing AWS context to AI models: Allows AI models to understand and respond to AWS-related queries by executing real-time commands.
• Examples: Listing S3 buckets, describing EC2 instances, listing Lambda functions with a specific profile.

FAQ about use_aws_mcp

Q: What are the prerequisites for using use_aws_mcp? A: You need Rust (1.70 or later), Cargo, AWS CLI installed and configured, and AWS credentials configured.

Q: How do I install use_aws_mcp? A: You can install it via cargo install use_aws_mcp.

Q: How does use_aws_mcp handle security? A: It executes AWS CLI commands, so proper AWS credentials and permissions are crucial. It also features read-only operation detection and recommends reviewing all commands before execution.

Q: What if I encounter issues? A: Common issues include AWS CLI not found, permission denied, invalid region, or parameter errors. You can enable debug mode by setting RUST_LOG=use_aws=debug for detailed logging.

use_aws MCP Server

🌟 amazon-q-cli is great, and it is great because it has use_aws MCP tool to interact with AWS API.

💡 Wouldn't it be greater if this use_aws was portable, and use it across different AI tools, whichever you're currently using?

⚡ use_aws_mcp is a standalone Model Context Protocol (MCP) server that provides AWS CLI functionality through a standardized interface.
This server replicates the functionality of the use_aws tool from the Amazon Q Developer CLI.

🎬 Demo

• Usage with Avante, MCPHub in nvim
  

• Usage with Cursor
  

✨ Features

• AWS CLI Integration: Execute AWS CLI commands with proper parameter handling
• Safety Checks: Automatic detection of read-only vs. write operations
• User Agent Management: Proper AWS CLI user agent setup for tracking
• Parameter Formatting: Automatic conversion of parameters to kebab-case for CLI compatibility
• Error Handling: Comprehensive error handling and output formatting
• MCP Protocol: Full Model Context Protocol compliance
• Human-Readable Descriptions: Rich command descriptions using terminal formatting

📦 Installation

📋 Prerequisites

• 🦀 Rust (1.70 or later), Cargo
  • for MacOS and linux, install with curl https://sh.rustup.rs -sSf | sh
• ☁️ AWS CLI installed and configured
• 🔑 AWS credentials configured (via AWS CLI, environment variables, or IAM roles)

🔨 Building

cargo build --release

The binary will be available at target/release/use_aws.

🚀 Usage

🔗 MCP Client Integration

To use this server with an MCP client, first install it using Cargo:

cargo install use_aws_mcp

Then configure your MCP client with:

{
  "mcpServers": {
    "use_aws_mcp": {
      "name": "use_aws_mcp",
      "command": "use_aws_mcp",
      "timeout": 300,
      "env": {},
      "disabled": false
    }
  }
}

⚠️ Important Caveat for Using MCP Client

With q cli, mcp clients are shell process, so credentials env like AWS_DEFAULT_PROFILE are automatically transfered to mcp server.

However, non shell mcp clients like cursor cannot take advantage of this, so it is best advised to require mcp clients directly to use specific aws profile.

📋 User Flow:

1. Set mcp.json above
2. Set API key, or login to specific profile using aws sso login
3. Ask away mcp client aws related questions! and be sure to require it to use specific profile.

Running the MCP Server Locally

./target/release/use_aws_mcp

The server communicates via stdin/stdout using JSON-RPC protocol.

Command Descriptions

The server provides human-readable descriptions of AWS CLI commands. You can see this in action by running the example:

cargo run --example description_demo

This will output something like:

Running aws cli command:

Service name: s3
Operation name: list-buckets
Parameters: 
- max-items: "10"
- query: "Buckets[].Name"
Profile name: development
Region: us-west-2
Label: List S3 buckets with query

✅ This command is read-only (no acceptance required)

🛠️ Tool Specification

The server provides a single tool called use_aws with the following schema:

{
  "name": "use_aws",
  "description": "Execute AWS CLI commands with proper parameter handling and safety checks",
  "inputSchema": {
    "type": "object",
    "properties": {
      "service_name": {
        "type": "string",
        "description": "AWS service name (e.g., s3, ec2, lambda)"
      },
      "operation_name": {
        "type": "string",
        "description": "AWS CLI operation name (e.g., list-buckets, describe-instances)"
      },
      "parameters": {
        "type": "object",
        "description": "Optional parameters for the AWS CLI command",
        "additionalProperties": true
      },
      "region": {
        "type": "string",
        "description": "AWS region (e.g., us-west-2, eu-west-1)"
      },
      "profile_name": {
        "type": "string",
        "description": "Optional AWS profile name"
      },
      "label": {
        "type": "string",
        "description": "Optional label for the operation"
      }
    },
    "required": ["service_name", "operation_name", "region"]
  }
}

📚 Examples

List S3 Buckets

{
  "name": "use_aws",
  "arguments": {
    "service_name": "s3",
    "operation_name": "ls",
    "region": "us-west-2"
  }
}

Describe EC2 Instances

{
  "name": "use_aws",
  "arguments": {
    "service_name": "ec2",
    "operation_name": "describe-instances",
    "region": "us-west-2",
    "parameters": {
      "instance-ids": "i-1234567890abcdef0"
    }
  }
}

List Lambda Functions with Profile

{
  "name": "use_aws",
  "arguments": {
    "service_name": "lambda",
    "operation_name": "list-functions",
    "region": "us-west-2",
    "profile_name": "development"
  }
}

🛡️ Safety Features

Read-Only Operation Detection

The server automatically detects read-only operations based on the operation name prefix:

• Read-only prefixes: get, describe, list, ls, search, batch_get
• Write operations: All other operations require explicit user acceptance

Output Truncation

Large outputs are automatically truncated to prevent memory issues, with a maximum response size of 100KB.

Development

Running Tests

cargo test

🔨 Building for Development

cargo build

Running with Logging

RUST_LOG=use_aws=debug cargo run

Examples

# Run the description demo
cargo run --example description_demo

Architecture

The project is structured as follows:

• src/lib.rs: Core library with types and constants
• src/error.rs: Error handling types
• src/use_aws.rs: Core AWS CLI functionality (replicated from original)
• src/mcp_server.rs: MCP server implementation
• src/main.rs: Binary entry point
• examples/description_demo.rs: Example demonstrating command descriptions

📦 Dependencies

If you do not have Cargo (the Rust package manager) installed, you can get it by installing Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the on-screen instructions to complete the installation. After installation, restart your terminal and ensure Cargo is available by running:

cargo --version

You should see the installed Cargo version printed.

This project is distributed as a Rust crate. The following dependencies are managed automatically by Cargo:

• tokio
• serde
• serde_json
• eyre
• bstr
• convert_case
• async-trait
• thiserror
• tracing
• tracing-subscriber
• crossterm

test/dev dependencies:

• tokio-test

You do not need to install these manually; Cargo will handle them during installation.

📄 License

MIT, Apache-2.0

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

🔒 Security

This server executes AWS CLI commands, which may have security implications:

• Ensure proper AWS credentials and permissions
• Review all commands before execution
• Use read-only operations when possible
• Consider running in a restricted environment

🔧 Troubleshooting

Common Issues

1. AWS CLI not found: Ensure AWS CLI is installed and in PATH
2. Permission denied: Check AWS credentials and permissions
3. Invalid region: Verify the region name is correct
4. Parameter errors: Check parameter names and values

Debug Mode

Run with debug logging to see detailed information:

RUST_LOG=use_aws=debug ./target/release/use_aws

References

• amazon-q-cli