README
¶
aws-mcp
🚧  UNDER CONSTRUCTION  🚧
This server is an early scaffold — a work in progress.
It runs over stdio with one read-only toolset wired end-to-end.
More toolsets are on the way (see the TODO list below).
APIs, configuration, and tool names may still change.
A Model Context Protocol (MCP) server, written
in Go, exposing AWS services as tools an LLM client (Claude Desktop/Code,
Cursor, and others) can call. Built on the official
aws-sdk-go-v2.
Features
- Typed tools with schemas: every tool has an auto-generated JSON Schema for its input and output, inferred from Go structs.
- Standard credential chain: credentials come from the environment, shared config, SSO, or an attached IAM role — no secrets stored by the server.
- Read-only switch:
AWS_READONLY=truehides every mutating tool. - Toolset filtering: enable only the services you need with
AWS_TOOLSETS.
Install
go install github.com/rangertaha/aws-mcp/cmd/aws@latest
Or build from source:
git clone https://github.com/rangertaha/aws-mcp
cd aws-mcp
make build # produces ./bin/aws
CLI
aws mcp # run the MCP server over stdio (default when no subcommand)
aws test # verify credentials (STS GetCallerIdentity)
Configuration
Credentials follow the standard AWS chain. Server behavior is configured with:
| Variable | Required | Description |
|---|---|---|
AWS_REGION |
no | Region (standard AWS variable; also the override). |
AWS_TOOLSETS |
no | Comma-separated toolset names to enable, or all. |
AWS_READONLY |
no | true to expose only read-only tools. |
Toolsets
| Toolset | Covers |
|---|---|
s3 |
list buckets (s3_list_buckets) and objects (s3_list_objects) |
TODO toolsets
ec2— describe instances, security groups, volumes.iam— list users, roles, and policies.lambda— list/get functions and configurations.cloudwatch— query metrics and logs.
Each new service follows the same pattern: a client in
internal/aws/aws.go, a package underinternal/aws/<service>/, and an entry ininternal/app/app.go.
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aws
command
Command aws runs the AWS Model Context Protocol server (`aws mcp`) and checks connectivity (`aws test`).
|
Command aws runs the AWS Model Context Protocol server (`aws mcp`) and checks connectivity (`aws test`). |
|
Package internal holds build-wide values shared across ado-mcp, such as the server version reported to MCP clients.
|
Package internal holds build-wide values shared across ado-mcp, such as the server version reported to MCP clients. |
|
app
Package app assembles the fully-configured aws-mcp server from configuration.
|
Package app assembles the fully-configured aws-mcp server from configuration. |
|
aws
Package aws holds the AWS SDK clients that the per-service tool packages (s3, …) share.
|
Package aws holds the AWS SDK clients that the per-service tool packages (s3, …) share. |
|
aws/s3
Package s3 exposes read-only Amazon S3 operations: listing buckets and the objects within a bucket.
|
Package s3 exposes read-only Amazon S3 operations: listing buckets and the objects within a bucket. |
|
config
Package config loads and validates runtime configuration for the aws-mcp server from environment variables.
|
Package config loads and validates runtime configuration for the aws-mcp server from environment variables. |
|
prompts
Package prompts registers MCP prompts: user-invoked, parameterized templates that clients surface as slash commands.
|
Package prompts registers MCP prompts: user-invoked, parameterized templates that clients surface as slash commands. |
|
server
Package server wires the Model Context Protocol server together: it owns the underlying mcp.Server, enforces the read-only policy, and exposes typed helpers that the per-area tool packages use to register tools.
|
Package server wires the Model Context Protocol server together: it owns the underlying mcp.Server, enforces the read-only policy, and exposes typed helpers that the per-area tool packages use to register tools. |
Click to show internal directories.
Click to hide internal directories.