If you've been following the AWS blog post " Build AWS architecture diagrams using Amazon Q CLI and MCP " to generate architecture diagrams, you may have noticed it no longer works. The awslabs.aws-diagram-mcp-server package has been completely yanked from PyPI, and the blog post hasn't been updated to reflect this change. I ran into this issue while setting up diagram generation for my infrastructure projects and spent time investigating the correct replacement. This post documents what changed and how to get diagram generation working again with the current tooling.
What Happened
When you try to run the MCP server referenced in the tutorial:
uvx awslabs.aws-diagram-mcp-server
You get:
No solution found when resolving tool dependencies:
Because awslabs-aws-diagram-mcp-server>=0.8.2025141004 was yanked
(reason: Superceeded by diagram agent skill in the deploy-on-aws plugin
https://github.com/awslabs/agent-plugins/tree/main/plugins/deploy-on-aws)
The diagram generation capability has been migrated from a standalone MCP server to an Agent Skill within the deploy-on-aws plugin in the awslabs/agent-plugins repository. The New Approach: Agent Skills
The replacement is actually a significant upgrade:
Aspect | Old (MCP Server) | New (Agent Skill) |
|---|
Output format | Static PNG via Graphviz | Editable .drawio XML |
Dependencies | Python diagrams + Graphviz | Only defusedxml for validation |
Icon set | Basic Python diagrams library | Official AWS4 icon library |
Dark mode | Not supported | Native light-dark() support |
Editability | None (raster image) | Full editing in draw.io |
Quality | Basic layout | AWS Reference Architecture style |
The new skill generates diagrams with professional styling: teal numbered step badges, color-coded category containers, proper Helvetica typography, and adaptive dark/light mode — matching the quality of official AWS Reference Architecture diagrams.
Quick Setup
1. Install the plugin
# Install bun if needed
curl -fsSL https://bun.sh/install | bash
# Install the deploy-on-aws plugin for Kiro CLI
COMPOUND_PLUGIN_GITHUB_SOURCE=https://github.com/awslabs/agent-plugins \
bunx @every-env/compound-plugin install deploy-on-aws --to kiro --output ~/.kiro
# Install XML validation dependency
sudo apt-get install -y python3-defusedxml
2. Add the knowledge MCP server
Add to ~/.kiro/settings/mcp.json :
{
"awsknowledge": {
"type": "http",
"url": "https://knowledge-mcp.global.api.aws"
}
}
3. Remove the deprecated server
If you have awslabs.aws-diagram-mcp-server in your MCP config, remove it entirely.
Usage
The skill activates automatically when you ask for diagrams in Kiro CLI:
Generate an architecture diagram for a serverless REST API with API Gateway, Lambda, DynamoDB
Or scan existing infrastructure code:
Analyze my codebase and generate an architecture diagram
The skill detects CloudFormation, CDK, Terraform, and Docker configurations automatically.
Results
Here are examples of diagrams generated with the new skill:
Serverless REST API:
Event-Driven Pipeline:
Key Takeaway
If you're hitting errors following the AWS blog post about diagram generation with MCP, the fix is straightforward:
- Remove
awslabs.aws-diagram-mcp-server from your config
- Install the
deploy-on-aws plugin (includes the aws-architecture-diagram skill)
- Use natural language prompts to generate
.drawio files
The new approach produces better results with fewer dependencies. Full step-by-step tutorial on my blog: matheuscosta.dev *Found this useful? I wrote this after spending time debugging the deprecated package issue. Hopefully it saves you the same trouble.
Loading article