# geopopos/higgsfield_ai_mcp architecture

> Architecture diagram of the GitHub repository geopopos/higgsfield_ai_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/geopopos/higgsfield_ai_mcp
- Repository: https://github.com/geopopos/higgsfield_ai_mcp

## Overview

Higgsfield AI MCP Server exposes image, video, talking-head, and character-generation operations, plus resources for browsing styles, motions, and characters. An MCP client invokes server tools or reads resources; the server delegates API work to the async client, which communicates with Higgsfield. The README documents the user workflow of browsing presets, starting generation, polling for results, and optionally creating reusable characters. The source excerpts show the server-to-client calls and client HTTP operations; unsampled server sections limit certainty about some tool implementations.

Main entry points: [`src/higgsfield_mcp/server.py`](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py) (MCP server), [`src/higgsfield_mcp/client.py`](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/client.py) (Async API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_server["MCP server<br/>[server.py]"]
end

subgraph group_generation["Generation workflows"]
  node_image["Image generation<br/>[server.py]"]
  node_video["Image-to-video<br/>[server.py]"]
  node_talking["Talking-head video<br/>[server.py]"]
  node_status["Job status and results<br/>[server.py]"]
end

subgraph group_references["Presets and characters"]
  node_resources["Preset resources<br/>[server.py]"]
  node_characters["Character references<br/>[server.py]"]
end

subgraph group_integration["API integration"]
  node_client["Async API client<br/>[client.py]"]
  node_higgsfield{{"Higgsfield API"}}
end

node_user(("MCP user"))
node_host(("MCP host"))

node_user -->|"requests tools"| node_host
node_host -->|"invokes tools"| node_server
node_server -.->|"registers tools"| node_image
node_server -.->|"registers tools"| node_video
node_server -.->|"registers tools"| node_talking
node_server -.->|"registers tools"| node_status
node_server -.->|"registers resources"| node_resources
node_server -.->|"registers tools"| node_characters
node_image -->|"starts generation"| node_client
node_video -->|"starts generation"| node_client
node_talking -->|"starts generation"| node_client
node_status -->|"fetches job"| node_client
node_resources -.->|"fetches presets"| node_client
node_characters -->|"manages references"| node_client
node_client -->|"sends API requests"| node_higgsfield
node_user -->|"browses presets"| node_resources
node_user -->|"polls job"| node_status
node_user -->|"creates references"| node_characters

click node_server "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_image "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_video "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_talking "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_status "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_resources "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_characters "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py"
click node_client "https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_user toneBlue
class node_image,node_video,node_talking,node_status toneAmber
class node_resources,node_characters toneMint
class node_client,node_higgsfield toneRose
class node_host toneIndigo
```

## Components

### MCP interface

- [MCP server](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`

### Generation workflows

- [Image generation](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`
- [Image-to-video](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`
- [Talking-head video](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`
- [Job status and results](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`

### Presets and characters

- [Preset resources](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`
- [Character references](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/server.py): `src/higgsfield_mcp/server.py`

### API integration

- [Async API client](https://github.com/geopopos/higgsfield_ai_mcp/blob/main/src/higgsfield_mcp/client.py): `src/higgsfield_mcp/client.py`
- **Higgsfield API**

### Other components

- **MCP user**
- **MCP host**

## Connections

- MCP user → MCP host: requests tools (evidence: `README.md`)
- MCP host → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Image generation: registers tools (evidence: `src/higgsfield_mcp/server.py`)
- MCP server → Image-to-video: registers tools (evidence: `src/higgsfield_mcp/server.py`)
- MCP server → Talking-head video: registers tools (evidence: `src/higgsfield_mcp/server.py`)
- MCP server → Job status and results: registers tools (evidence: `src/higgsfield_mcp/server.py`)
- MCP server → Preset resources: registers resources (evidence: `src/higgsfield_mcp/server.py`)
- MCP server → Character references: registers tools (evidence: `src/higgsfield_mcp/server.py`)
- Image generation → Async API client: starts generation (evidence: `src/higgsfield_mcp/server.py`)
- Image-to-video → Async API client: starts generation (evidence: `src/higgsfield_mcp/server.py`)
- Talking-head video → Async API client: starts generation (evidence: `src/higgsfield_mcp/server.py`)
- Job status and results → Async API client: fetches job (evidence: `src/higgsfield_mcp/server.py`)
- Preset resources → Async API client: fetches presets (evidence: `src/higgsfield_mcp/server.py`)
- Character references → Async API client: manages references (evidence: `src/higgsfield_mcp/server.py`)
- Async API client → Higgsfield API: sends API requests (evidence: `src/higgsfield_mcp/client.py`)
- MCP user → Preset resources: browses presets (evidence: `README.md`)
- MCP user → Job status and results: polls job (evidence: `README.md`)
- MCP user → Character references: creates references (evidence: `README.md`)
