Getting Started

Create a free account and get your API key

Sign up at umlforge.dev/signup. No credit card required. The free plan gives you 5 diagrams per month across all 13 tools.

After signing up, go to your dashboard → API Keys → Create key. Copy the key that appears — it is shown only once.

Install uv (if you don't have it already)

UML Forge is distributed as a Python package and runs via uvx — a tool that installs and runs Python packages in isolated environments with no setup required. You only need to install it once.

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

After installing, restart your terminal and verify with uvx --version.

Add UML Forge to your coding agent

UML Forge connects to your coding agent via the Model Context Protocol (MCP). Find your agent below, copy the configuration block, replace uf_live_your_key_here with your actual API key, and save the file.

Restart your agent after saving — it needs to reload its MCP server list.

{
  "mcpServers": {
    "umlforge": {
      "command": "uvx",
      "args": ["umlforge"],
      "env": {
        "UMLFORGE_API_KEY": "uf_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "umlforge": {
      "command": "uvx",
      "args": ["umlforge"],
      "env": {
        "UMLFORGE_API_KEY": "uf_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "umlforge": {
      "command": "uvx",
      "args": ["umlforge"],
      "env": {
        "UMLFORGE_API_KEY": "uf_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "umlforge": {
      "command": "uvx",
      "args": ["umlforge"],
      "env": {
        "UMLFORGE_API_KEY": "uf_live_your_key_here"
      }
    }
  }
}

Verify the connection

Open a conversation in your coding agent and ask it to list its available tools. You should see all 13 UML Forge tools beginning with umlforge_.

If the tools do not appear, the most common causes are:

• You did not restart the agent after saving the configuration
• The API key in the config still says uf_live_your_key_here — replace it with your real key
• uvx is not installed or not on your PATH — run uvx --version in your terminal to check

Generate your first diagram

Not sure which tool to use? Start with umlforge_suggest — describe what you want to achieve in plain English and it will recommend the right tool with all parameters pre-filled and ready to run:

Use umlforge_suggest with:
task_description: "I want to diagram how a user places an order —
the request goes through an API gateway, hits the Order Service,
calls Stripe for payment, then sends a confirmation email."

Or call a tool directly. Here is a typical first call:

Use umlforge_api_sequence with:
services: "API Gateway, Order Service, Payment Service, Notification Service"
user_journey: "User places an order — payment is processed and a confirmation email is sent"

Every tool returns a ```mermaid diagram rendered inline in your agent. You can also paste the code block into GitHub, Notion, or any Markdown editor to view and share it.

Upgrade to Pro for unlimited diagrams and Guided Mode

The free plan includes 5 diagrams per month. Pro users get unlimited diagrams and unlock Guided Mode — before generating, UML Forge asks 3 targeted questions about your system. The answers are used to produce significantly more accurate and detailed diagrams, especially for complex architectures.

After upgrading, enable Guided Mode by adding one line to your MCP configuration:

{
  "mcpServers": {
    "umlforge": {
      "command": "uvx",
      "args": ["umlforge"],
      "env": {
        "UMLFORGE_API_KEY": "uf_live_your_key_here",
        "UMLFORGE_GUIDED_MODE": "true"
      }
    }
  }
}

Restart your agent after adding the line.