Archy

Archy MCP Server lets you generate architectural diagrams in Mermaid syntax from natural language descriptions or GitHub repositories. It supports all Mermaid diagram types and can integrate AI-powered features when OpenRouter is configured, making diagram creation fast and repeatable for documentation, design reviews, and project planning.

How to use

You interact with Archy through an MCP client that talks to the Archy server. You can describe the diagram you want in plain language or point Archy at a GitHub repository. Archy will return a Mermaid diagram code (or multiple diagrams) that you can render in your docs or tools. When OpenRouter API access is configured, you gain access to AI-assisted diagram generation, code-to-diagram generation, and difference visualizations, which helps you craft more sophisticated diagrams from descriptions or code changes.

How to install

Prerequisites you need before installing Archy MCP Server:

• Node.js v16 or higher

• npm v7 or higher

• TypeScript v5.8 or higher (included in dependencies)

How to install

Step 1: Install from source

Clone the project and install dependencies

git clone https://github.com/phxdev1/archy.git
cd archy
npm install

Step 2: Build the project

npm run build

Step 3: Install the MCP configuration for Archy

npm run install-mcp

Configuration

Archy can read its configuration from environment variables and MCP settings provided during startup. The following environment variables are commonly used:

• GITHUB_TOKEN: GitHub API token for authenticated repository analysis (optional)

• OPENROUTER_API_KEY: OpenRouter API key for AI-powered diagram generation (optional)

MCP integration configuration example

To use Archy with an MCP client, add it to your MCP settings with a local stdio server configuration. The complete command to run Archy locally is shown here.

{
  "mcpServers": {
    "archy": {
      "command": "node",
      "args": ["/path/to/archy/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

OpenRouter integration and AI features

If you configure an OpenRouter API key, Archy enables enhanced AI-powered diagram generation. This includes AI-assisted text-to-diagram rendering, code-to-diagram analysis, and diff visualizations to show changes over time.

Image export and repository evolution

Archy can export Mermaid diagrams to PNG, SVG, or PDF with configurable dimensions and background color. It also offers repository evolution diagrams by analyzing commit histories and file changes over time.

Step 4: Start the server and connect your MCP client

Sources of runtime data and tools

Archy provides the following core diagram generation capabilities when accessed via MCP:

• generate_diagram_from_text: Create a Mermaid diagram from a natural language description.

• generate_diagram_from_github: Create a Mermaid diagram from a GitHub repository.

• list_supported_diagram_types: List all supported diagram types and their descriptions.

Notes

If you need to customize startup, ensure the path to the built index file in the MCP config matches your environment after running the build. The GITHUB_TOKEN value is optional but recommended for repository analysis.

Examples

Example MCP config to run Archy locally via Node.js

{
  "mcpServers": {
    "archy": {
      "command": "node",
      "args": ["/path/to/archy/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Available tools

generate_diagram_from_text

Generates a Mermaid diagram from a natural language description.

generate_diagram_from_github

Generates a Mermaid diagram from a GitHub repository.

list_supported_diagram_types

Lists all supported diagram types with their descriptions.

generate_diagram_from_text_with_ai

Generates a Mermaid diagram from text using AI (OpenRouter) with optional advanced model.

generate_diagram_from_code

Generates a Mermaid diagram from code using AI.

generate_diff_diagram

Generates a Mermaid diagram showing differences between two versions of code.

export_diagram_to_image

Exports a Mermaid diagram to PNG, SVG, or PDF.

generate_repository_evolution_diagram

Generates a diagram showing repository evolution over time.