Blueprint MCP: Let AI Diagram Your Codebase
Ever spent hours whiteboarding a system architecture, only to have it become outdated after the next PR? Or jumped into a new codebase and wished you could just see how everything connects? There's a new tool that's tackling this exact problem, and it's using AI in a way that feels genuinely useful, not just flashy.
Enter Blueprint MCP, a project from ArcadeAI that turns your code into detailed diagrams automatically. It's not another static documentation generator. Instead, it's a Model Context Protocol (MCP) server that works with AI assistants like Claude to generate and update visual representations of your systems on the fly.
What It Does
In simple terms, Blueprint MCP is a bridge. It connects an AI assistant to diagramming tools (like Mermaid.js) and your code. You ask your AI assistant (e.g., "Claude, can you show me the architecture of our authentication service?"), and Claude uses the Blueprint MCP server to read the relevant files, understand the structure, and generate a visual diagram as part of its response.
It's designed to understand different aspects of your project:
- System Architecture: High-level component diagrams.
- Codebase Structure: Directory and module relationships.
- Data Flow: How information moves through services.
- Sequence Diagrams: Interactions over time.
Why It's Cool
The clever part is the use of the Model Context Protocol. MCP is an emerging standard for giving AI models access to tools and data. Blueprint MCP isn't a standalone app with a clunky UI; it's a server that plugs directly into your existing AI workflow. This means the diagrams are generated in the context of your conversation, based on the files you're currently discussing.
It's dynamic. Instead of a one-time export, you can ask for different views or ask for a diagram to be updated after discussing a code change. It treats the diagram as a living artifact of the development conversation. The fact that it outputs standard Mermaid.js code is also a win—you can take that code and drop it into your markdown docs, Notion pages, or PR descriptions immediately.
How to Try It
Ready to see it in action? The project is open source on GitHub.
- Head over to the ArcadeAI/blueprint-mcp repository.
- You'll need an AI assistant that supports MCP servers (like Claude Desktop).
- Follow the setup instructions in the README to configure the MCP server. It involves cloning the repo, installing dependencies, and adding a config to your AI client.
- Once connected, just start a conversation with your assistant and ask it to diagram something from your code.
The repo has clear steps to get you going. It's a bit of a setup, but it's a one-time thing to unlock diagramming superpowers in your AI chats.
Final Thoughts
As codebases grow and teams change, keeping mental (and documented) models in sync is a real challenge. Blueprint MCP feels like a pragmatic step towards solving that. It lowers the barrier to creating useful visuals from the get-go, right where you're already working—in your chat with an AI assistant.
It won't replace thoughtful, high-level architecture diagrams, but for exploring a new module, documenting a quick design in a PR, or understanding a legacy service, this could be a huge time-saver. It's one of those tools that feels less like "AI for AI's sake" and more like a practical lever to make us more effective.
Give it a spin the next time you're diving into unfamiliar code. You might just save yourself a few hours of drawing boxes and arrows.
@githubprojects