Hitomi

Creations become reality. A unified MCP (Model Context Protocol) server for AI illustration, voice, and vision generation — powered by a local ComfyUI instance.

Hitomi is the studio layer for an AI agent's creative work. One server, one config, one toolset covering:

Illustration — anime, therian (anthro), realistic, text-in-image
Voice — expressive TTS with emotion tags (Fish Audio S2-pro)
Vision — agents can describe / review their own output (JoyCaption-ready)
Pipelines — sequential multi-model workflows (e.g. ERNIE panel + Nova Furry character)

It is built on top of joenorton/comfyui-mcp-server (thank you Joe) and merges the creative stack originally developed in chi-image.

Status

Scaffold — active development.

This repository is the public home of a work-in-progress merge. The upstream comfyui-mcp-server foundation (self-start, asset registry, workflow engine, publish pipeline) is present and working. The chi-image feature set (style profiles, NSFW-aware tag handling, LoRA parser, regional prompting via AttentionCouplePPM, Fish S2 voice tool) is being ported in — see HITOMI_MERGE_TODO.md for the full checklist and architectural notes.

If you want the stable upstream image-only server, use joenorton/comfyui-mcp-server directly.

Install

1) Prerequisites

Python 3.10+
A local ComfyUI install (Hitomi self-starts it, but you install it once)
~24 GB VRAM recommended for the full pipeline (sequential model loading works at 16 GB)
Git + pip

2) Custom ComfyUI nodes

Install these into <ComfyUI>/custom_nodes/ (clone + pip install -r requirements.txt inside each):

Node	Purpose	Source
ComfyUI-FishAudioS2	Fish S2-pro voice synthesis inside ComfyUI graphs	https://github.com/Saganaki22/ComfyUI-FishAudioS2
AttentionCouplePPM	Regional prompting for multi-character scenes	community
JoyCaption (optional)	NSFW-aware image description for vision tools	community

3) Models

Download into <ComfyUI>/models/checkpoints/ (or let Hitomi's asset pipeline resolve them):

Model	Role	Source
Nova Furry XL IL v17	Primary therian / anthro illustration model	https://civitai.com/models/503815/nova-furry-xl
ERNIE-Image	Panel-layout + in-image text + manga backgrounds	https://civitai.com/models/2548387/ernieimage

LoRAs into <ComfyUI>/models/loras/:

LoRA	Why	Notes
furry-genitals anatomy correction	Required even for clothed characters — stabilizes tail, hip, and limb anatomy on Nova Furry	CivitAI
Character LoRAs	Your character faces / outfits	Train per character

Voice model (separate from ComfyUI checkpoints):

Model	Source
Fish S2-pro GGUF (f16, ~12 GB)	https://huggingface.co/rodrigomt/s2-pro-gguf

4) Clone and install Hitomi

git clone https://github.com/grimmjoww/hitomi.git
cd hitomi
pip install -r requirements.txt

5) Run ComfyUI (or let Hitomi start it)

cd <ComfyUI_dir>
python main.py --port 8188

Hitomi expects ComfyUI at http://127.0.0.1:8188 (not 8000 — this is a difference from chi-image). If ComfyUI isn't running, Hitomi will attempt to start it via exponential-backoff retry.

6) Run Hitomi

python server.py

Server listens on http://127.0.0.1:9000/mcp.

7) Register with your MCP client

{
  "mcpServers": {
    "hitomi": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

Restart your client; Hitomi's tools should appear.

Tool categories

Generation

generate_image — one-shot illustration (prompt + optional style profile + LoRAs)
generate_couple (pending merge) — regional-prompt two-character scene via AttentionCouplePPM
generate_voice (pending merge) — Fish S2-pro voice synthesis with emotion tags
generate_song — audio generation (upstream)
regenerate — iterate on an existing asset with parameter overrides

Pipelines (pending merge)

pipeline_manga_panel — ERNIE (panel + text) → unload → Nova Furry (character refinement). Designed for 16 GB VRAM; Hitomi unloads stage 1 before loading stage 2.

Review / vision (pending merge)

describe_image — JoyCaption-backed NSFW-aware description
review_asset — agent self-review loop (describe → critique → regenerate)

Assets & jobs

view_image, list_assets, get_asset_metadata
get_queue_status, get_job, cancel_job

Configuration

list_models, get_defaults, set_defaults
list_workflows, run_workflow

Publish

get_publish_info, set_comfyui_output_root, publish_asset

Style profiles (pending merge)

Hitomi ships with named profiles that bundle base prompts, negatives, and recommended LoRAs/models:

Profile	Use for	Base model
`anime`	Human / humanoid, full-color illustration	Illustrious checkpoint
`therian`	Anthro / furry characters (synonymous with `furry` tag for searchability)	Nova Furry XL IL v17
`nova`	Nova-v17-specific prompt patterns	Nova Furry XL IL v17
`manga_panel`	Black-white linework + in-panel text	ERNIE
`poster`	Text-heavy composition	ERNIE

Terminology note. Documentation prefers therian (the less derogatory term for anthropomorphic characters / humans with animal features). GitHub tags use furry for community searchability. Both refer to the same style family.

Color default. Full-color illustration is the default output. Manga is black-and-white only because coloring is expensive for human artists — Hitomi has no such constraint.

Voice (pending merge)

Voice generation runs through the ComfyUI-FishAudioS2 node using Fish S2-pro. Emotion tags are inline:

(excited) Welcome home! (laugh) I missed you.

Supported tags include (excited), (sad), (laugh), (whisper), (moan), and others the S2-pro model recognizes. See the Fish Audio docs for the full set.

Configuration

Defaults resolution order: per-call → runtime (set_defaults) → config file (~/.config/hitomi/config.json) → env (HITOMI_DEFAULT_*) → hardcoded.

Common env vars:

Var	Purpose
`COMFYUI_HOST`	Default `127.0.0.1`
`COMFYUI_PORT`	Default `8188`
`HITOMI_COMFYUI_AUTOSTART`	`1` to enable self-start with retry
`HITOMI_COMFYUI_CMD`	Command to start ComfyUI (e.g. `python main.py --port 8188`)
`HITOMI_COMFYUI_CWD`	Working dir for the start command

Security

Hitomi binds to localhost by default. Do not expose publicly without a reverse proxy + auth. The server executes whatever workflows you place in workflows/ — treat third-party workflow JSON as untrusted code.

Project layout

hitomi/
├── server.py                 # MCP entry point
├── comfyui_client.py         # ComfyUI API client (upstream)
├── asset_processor.py        # Image processing (upstream)
├── managers/
│   ├── workflow_manager.py
│   ├── defaults_manager.py
│   ├── asset_registry.py
│   ├── publish_manager.py
│   └── style_manager.py      # NEW — style profiles (stub, being merged)
├── tools/
│   ├── generation.py
│   ├── asset.py
│   ├── job.py
│   ├── configuration.py
│   ├── workflow.py
│   ├── publish.py
│   └── voice.py              # NEW — Fish S2-pro voice tools (stub, being merged)
├── workflows/
│   ├── generate_image.json
│   ├── generate_song.json
│   ├── generate_couple.json  # NEW — regional prompting (stub, being merged)
│   └── generate_voice.json   # NEW — Fish S2 (stub, being merged)
├── models/                   # Pydantic data models
├── docs/
├── HITOMI_MERGE_TODO.md      # Live merge checklist
├── CONTRIBUTING.md
├── NOTICE
└── LICENSE                   # Apache 2.0

License

Apache License 2.0. Dual attribution:

See LICENSE and NOTICE for full detail.

Acknowledgements

@joenorton — comfyui-mcp-server, the clean architecture this stack is built on
@venetanji — upstream streamable-http transport & PARAM_* workflow system
@Saganaki22 — ComfyUI-FishAudioS2
The ComfyUI, Fish Audio, CivitAI, and JoyCaption communities

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Hitomi

Status

Install

1) Prerequisites

2) Custom ComfyUI nodes

3) Models

4) Clone and install Hitomi

5) Run ComfyUI (or let Hitomi start it)

6) Run Hitomi

7) Register with your MCP client

Tool categories

Generation

Pipelines (pending merge)

Review / vision (pending merge)

Assets & jobs

Configuration

Publish

Style profiles (pending merge)

Voice (pending merge)

Configuration

Security

Project layout

License

Acknowledgements

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 42 Commits
.cursor		.cursor
.github		.github
docs		docs
managers		managers
models		models
tests		tests
tools		tools
workflows		workflows
.gitignore		.gitignore
.mcp.json		.mcp.json
CONTRIBUTING.md		CONTRIBUTING.md
HITOMI_MERGE_TODO.md		HITOMI_MERGE_TODO.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
asset_processor.py		asset_processor.py
comfyui_client.py		comfyui_client.py
mcp.json		mcp.json
requirements.txt		requirements.txt
server.py		server.py
test_client.py		test_client.py

Folders and files

Latest commit

History

Repository files navigation

Hitomi

Status

Install

1) Prerequisites

2) Custom ComfyUI nodes

3) Models

4) Clone and install Hitomi

5) Run ComfyUI (or let Hitomi start it)

6) Run Hitomi

7) Register with your MCP client

Tool categories

Generation

Pipelines (pending merge)

Review / vision (pending merge)

Assets & jobs

Configuration

Publish

Style profiles (pending merge)

Voice (pending merge)

Configuration

Security

Project layout

License

Acknowledgements

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages