@spayse/mcp

Model Context Protocol server for Spayse to create, edit, export, and manage architecture diagrams via natural language.

What it is

Spayse is a precision canvas for technical diagrams that lets you build and modify system architecture, API flows, and databases using natural language. The Spayse MCP server exposes this canvas to AI agents and IDEs, allowing assistants like Claude, Cursor, and Windsurf to generate, edit, and export visual architecture diagrams autonomously as they write code.

Quick Start

Add the following configuration to your MCP settings file (e.g. claude_desktop_config.json or Cursor's MCP settings):

{
  "mcpServers": {
    "spayse": {
      "command": "npx",
      "args": ["-y", "@spayse/mcp"]
    }
  }
}

Installation

Run via npx (Recommended)

Use npx in your MCP config to run the server on demand without managing global package installations:

"command": "npx",
"args": ["-y", "@spayse/mcp"]

Install globally

Use global installation if you prefer to pin the server version and run it locally with the spayse-mcp binary:

# Install globally
npm install -g @spayse/mcp

# Reference in MCP server config
"command": "spayse-mcp"

Commands / Usage

CLI Commands

| Command | Description | | :--- | :--- | | spayse-mcp login | Authenticates your terminal session and saves credentials. | | spayse-mcp --http | Runs a standalone persistent HTTP server. |

Exposed MCP Tools

| Tool Name | Description | Inputs | | :--- | :--- | :--- | | create_diagram | Generates a new diagram from a natural language description. | description, diagram_type?, model? | | update_diagram | Modifies an existing diagram based on natural language instructions. | instruction, dsl? or diagram_id?, model?, output_path? | | get_diagram_code | Retrieves the Spayse DSL source code for a saved diagram ID. | diagram_id | | list_diagrams | Lists all saved diagrams in the project directory. | directory?, limit?, sort_by? (name, modified, created) | | export_diagram | Exports a diagram to DSL, formatted DSL, or JSON. | diagram_id, format (dsl, formatted-dsl, json), output_path? | | delete_diagram | Deletes a saved diagram file. | diagram_id | | validate_dsl | Checks a Spayse DSL source string for syntax and semantic errors. | dsl |

Configuration

| Name | Description | Default / Location | | :--- | :--- | :--- | | ~/.spayse/auth.json | Stores local authentication credentials after login. | Saved on login | | SPAYSE_API_KEY | Developer API key used for headless auth in CI/CD or agents. | None | | SPAYSE_APP_URL | Configures the target Spayse server endpoint. | https://spayse.app | | PORT | Local port number to bind when running standalone in HTTP mode. | 3100 |

Authentication Modes

We support three authentication options to fit your workflow:

1. Interactive OAuth (Default for Local Stdio): Run npx @spayse/mcp login in your terminal to link your account using a browser authentication flow.
2. API Key: Generate a developer key from your dashboard and authenticate without browser interaction by setting the SPAYSE_API_KEY environment variable.
3. Headless / CI: Pass the SPAYSE_API_KEY environment variable directly in your CI pipeline or server environment to run without interactive prompts.

Feature Tiers

| Feature / Limit | Free Tier | Pro Tier | | :--- | :--- | :--- | | Generation Limit | 5 diagrams per month | Unlimited | | Preview Image | Watermarked SVG | Clean, High-Res SVG | | Share Link | Not returned (Private only) | Direct shareable public link | | Web Editor Link | Included | Included |

Related Packages

• @spayse/cli - Interactive terminal interface and REPL shell to build, manage, and export diagrams locally.

Links

• Documentation
• Dashboard
• Changelog
• Issues

License

MIT