> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install ComfyUI and connect the MCP server — local, remote, or Comfy Cloud.

## 1. Install ComfyUI

<CardGroup cols={2}>
  <Card title="ComfyUI Desktop" icon="desktop" href="https://www.comfy.org/download">
    The easiest way to get a managed install on macOS / Windows.
  </Card>

  <Card title="From source" icon="github" href="https://github.com/comfyanonymous/ComfyUI">
    Clone and run manually — or use the [`install_comfyui`](./tools/install-environment) tool.
  </Card>
</CardGroup>

## 2. Add the MCP server

ComfyUI MCP ships on npm as `comfyui-mcp` and runs via `npx` — no global install needed.

<Tabs>
  <Tab title="Local ComfyUI">
    The server auto-detects a local install and its port. Add it to `~/.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "comfyui": {
          "command": "npx",
          "args": ["-y", "comfyui-mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Remote ComfyUI">
    Point at any reachable instance with `--comfyui-url`. No local install is required for
    HTTP-based tools (generation, queue, workflows, models search, etc.). When the host is
    non-loopback, the server enters **remote mode** and skips `COMFYUI_PATH` auto-detection
    so a stale local install can't silently absorb uploads.

    ```json theme={null}
    {
      "mcpServers": {
        "comfyui": {
          "command": "npx",
          "args": ["-y", "comfyui-mcp", "--comfyui-url", "https://my-comfy.example.com"]
        }
      }
    }
    ```

    <Note>
      Local-only tools (installing ComfyUI/custom nodes, removing model files, reading logs)
      need a local install path and will return a clear error in remote mode. See
      [How it works](./concepts).
    </Note>
  </Tab>

  <Tab title="Comfy Cloud">
    Target [Comfy Cloud](https://cloud.comfy.org) by setting `COMFYUI_API_KEY`. The server
    enters **cloud mode**: HTTP primitives route via `cloud.comfy.org` with `X-API-Key`
    authentication. WebSocket-bound and local-FS/process tools throw a clear
    `CLOUD_UNSUPPORTED` error.

    ```json theme={null}
    {
      "mcpServers": {
        "comfyui": {
          "command": "npx",
          "args": ["-y", "comfyui-mcp"],
          "env": {
            "COMFYUI_API_KEY": "your-comfy-cloud-api-key"
          }
        }
      }
    }
    ```

    <Note>
      Cloud mode skips local `COMFYUI_PATH` auto-detection and uses the cloud's own model
      library — `list_local_models`, `apply_manifest`, and other local-only tools throw
      `CLOUD_UNSUPPORTED`. See the [Configuration](./configuration#deployment-modes) page
      for the full feature-parity matrix.
    </Note>

    <Note>
      **Cloud-only?** [Comfy-Org's Comfy Cloud MCP](https://docs.comfy.org/agent-tools) (public beta) is the canonical choice — see [Local vs. Comfy Cloud](./local-vs-comfy-cloud). Use `comfyui-mcp`'s cloud-mode if you want a single MCP across local / remote / cloud, or you need cloud support today.
    </Note>
  </Tab>
</Tabs>

Then run `/mcp` in Claude Code to connect.

## 3. (Optional) Tokens

Some tools use API tokens. Set them in the server's `env` block (see [Configuration](./configuration)):

* `CIVITAI_API_TOKEN` — gated CivitAI downloads
* `HUGGINGFACE_TOKEN` — higher HuggingFace rate limits
* `GITHUB_TOKEN` — skill generation / node metadata fetches
* `COMFY_API_KEY` — hosted comfy.org API nodes

## Local development

The project uses `npm link` so `npx comfyui-mcp` resolves to your local build:

```bash theme={null}
git clone https://github.com/artokun/comfyui-mcp
cd comfyui-mcp
npm install
npm run build
npm link
```

After code changes: `npm run build`, then `/mcp` to reconnect.