mcp-aws-solution-architect
MCP server that turns any AI assistant into a copilot for AWS Solution Architects.
git clone https://github.com/fernandofatech/mcp-aws-solution-architect.gitmcp-aws-solution-architect is a Python MCP server that exposes five deterministic tools — service suggestion, diagram generation, cost estimation, Well-Architected review, and ADR authoring — to any MCP-aware client such as Claude Desktop, Cursor, or a custom agent.
Why this exists
Solution Architects repeat the same shaping work on every engagement: mapping a use case to the right AWS services, sketching an architecture diagram, sanity-checking against the Well-Architected Framework, rough-sizing a monthly cost, and writing an ADR before the decision fades from memory. None of that requires an LLM to be useful — it needs structure, consistency, and speed.
This server packages those tasks as callable MCP tools. The client (Claude Desktop, Cursor, Cline, Continue, or any agent that speaks the Model Context Protocol) decides when to invoke them; the server returns structured, typed output. There is no hidden LLM dependency: the tools run deterministically against an embedded AWS service catalog and pricing table. An optional Amazon Bedrock backend can be wired in for richer, generative output, but it is not required to ship.
The project also serves as a portfolio artifact. It is production-shaped: typed with mypy, linted with Ruff, tested with pytest, scanned with CodeQL, Trivy, Gitleaks, and pip-audit, and deployed through GitHub Actions. The documentation site runs on MkDocs Material; the landing page is a dependency-free static build deployed to Vercel. Everything a real service needs is here, at a scale appropriate for a single-author open-source project.
What the five tools do
{service, usage} items using an embedded pricing table; no AWS API call required.How a request flows through the system
The MCP client sends a tool call over stdio transport. The server routes it to the appropriate tool, which reads from local data (catalog, pricing) and optionally calls Amazon Bedrock before returning structured output.
- Claude Desktop · Cursor / Cline · Custom Agent
- mcp-aws-sa · stdio transport
- Tools Layer · 5 typed tools
- Service Catalog · + Pricing Table
- Amazon Bedrock · Claude / Nova
Install and wire it up
- 1
Clone and create a virtual environment
Python 3.11 or newer is required. Clone the repo and isolate dependencies in a venv before installing anything.
- 2
Install in editable mode with dev extras
Running
pip install -e '.[dev]'installs the package plus Ruff, mypy, pytest, and other dev tooling declared inpyproject.toml. - 3
Start the MCP server
The
mcp-aws-saentry point starts the server on stdio transport. It stays running and waits for tool-call messages from a connected client. - 4
Register the server in Claude Desktop
Edit
~/Library/Application Support/Claude/claude_desktop_config.jsonto add theaws-solution-architectentry undermcpServers, then restart Claude Desktop. The five tools become available in every chat session. - 5
Send a multi-tool prompt to verify
Ask the assistant to suggest services, generate a diagram, and estimate cost for a single scenario. The client will chain the three tool calls automatically and return consolidated output.
# 1. Clone
git clone git@github.com:fernandofatech/mcp-aws-solution-architect.git
cd mcp-aws-solution-architect
# 2. Virtual environment
python -m venv .venv && source .venv/bin/activate
# 3. Install (with dev extras for lint/test)
pip install -e ".[dev]"
# 4. Run the server (stdio transport — keep this terminal open)
mcp-aws-sa
# 5. In a second terminal: run the test suite
pytest
# 6. Lint + type-check
ruff check . && mypy src/{
"mcpServers": {
"aws-solution-architect": {
"command": "mcp-aws-sa",
"args": []
}
}
}Engineering hygiene and CI pipeline
The repository is structured as a production-shaped project, not a script dropped in a folder. The source lives under src/mcp_aws_sa/, which enforces proper packaging. Tests live in tests/ and run under pytest. The docs/ directory is a full MkDocs Material site that builds strictly and deploys to GitHub Pages on every push to main. The frontend/ directory is a dependency-free static landing page that deploys to Vercel via Git integration, with automatic preview URLs on pull requests.
The CI pipeline covers several layers. Code quality: Ruff for linting and formatting, mypy for static type checking. Security: CodeQL for SAST, pip-audit for known CVEs in Python dependencies, Trivy for filesystem scanning, Gitleaks for secret detection, and GitHub's dependency review action on every pull request. Frontend: npm lint, static build verification, and npm audit. Maintenance: Dependabot is configured for GitHub Actions, Python dependencies, and frontend dependencies separately, so version bumps arrive as small, reviewable PRs rather than accumulating drift.
Conventional Commits is enforced, which keeps the git log machine-readable and makes changelog generation straightforward. The full list of workflows and the secrets they require is documented in OPERATIONS.md.
Deterministic by default, generative when needed
All five tools run without any LLM or external API call. The service catalog and pricing data are embedded in the package. This means the server starts instantly, works offline, and produces consistent output across runs — useful when you need reproducible results in a CI pipeline or a demo that cannot depend on network availability. Amazon Bedrock is an optional layer you can enable when richer, context-aware output is worth the latency and cost.
Common questions
Does this work with clients other than Claude Desktop?
Yes. Any client that implements the Model Context Protocol over stdio transport will work: Cursor, Cline, Continue, or a custom agent. The server does not assume anything about the client beyond the MCP spec.
Are the cost estimates accurate enough to use in a proposal?
No. They are rough order-of-magnitude figures from an embedded static pricing table. Use them for quick sanity checks and internal discussions, not for customer-facing commitments. For accurate estimates, use the AWS Pricing Calculator with your specific configuration.
Can I add my own tools?
Yes. The tools layer is in src/mcp_aws_sa/. Each tool is a typed Python function registered with the MCP server. Adding a new tool means writing the function, registering it, and adding tests. The architecture document in ARCHITECTURE.md covers the extension points.
What does the frontend directory contain?
A dependency-free static landing page (HTML, CSS, JavaScript) deployed to Vercel. It is separate from the MkDocs documentation site, which deploys to GitHub Pages. The landing is at mcp-aws.moretes.com; the docs are at the GitHub Pages URL.
Who this is for and when to use it
This project is directly useful if you work as a Solutions Architect or technical lead and already use an MCP-aware assistant in your daily workflow. The five tools cover the most repetitive shaping tasks — service selection, diagramming, cost sizing, Well-Architected review, and decision documentation — without requiring you to craft long prompts or remember framework details each time. It is also a concrete reference if you are building your own MCP server in Python. The project demonstrates a complete setup: typed tools, embedded data, optional LLM backend, full CI with security scanning, documentation site, and a static landing page — all wired together and publicly visible. It is not a replacement for the AWS Pricing Calculator, the official Well-Architected Tool, or a proper architecture review. The cost estimates are rough, the WAR findings are lightweight, and the diagrams are starting points. The value is speed and structure in the early shaping phase, not precision at the decision gate.