{
  "markdown": "# NovelAI Image MCP\n\n[![CI][ci-badge]][ci-workflow]\n[![Docs][docs-badge]][docs]\n[![License: MIT][mit-badge]][license]\n[![Python 3.13+][python-badge]][python]\n[![uv][uv-badge]][uv]\n[![REUSE status][reuse-badge]][reuse]\n[![DeepWiki][deepwiki-badge]][deepwiki]\n[![skills.sh][skills-badge]][skills-sh]\n\n[![NovelAI Image MCP - MCP server for integrating NovelAI Image generation into AI | Product Hunt][product-hunt-badge]][product-hunt] [![Featured on Lifto][lifto-badge]][lifto]\n\nAn [MCP (Model Context Protocol)][mcp] server that\nexposes **NovelAI image generation** as tools for AI agents (Claude Desktop,\nCline, custom agents, remote clients).\n\nBuilt on FastMCP 4 (the fastmcp framework over the MCP SDK v2 `mcp>=2.0.0`), it lets an agent generate\nimages (txt2img / img2img / inpaint), upscale, run Director tools (line art,\nemotion, background removal, …), annotate with ControlNet, suggest tags, encode\nvibes, and query account subscription — all through the standard MCP tool\ninterface.\n\n> 📖 **Documentation**: [xinvxueyuan.github.io/NovelAI-Image-MCP][docs]\n\n## Features\n\n- **11 MCP tools** covering the full NovelAI image API surface.\n- **Two transports**: stdio (local agents) + streamable-http (remote / multi-client).\n- **Dual image return**: base64 `Image` content blocks (the agent *sees* the image)\n  **and** PNG saved to disk (path returned as text).\n- **Async + sync**: async tool handlers + a `typer` CLI for direct invocation.\n- **Monorepo**: uv workspace (Python) + pnpm workspace (Node tooling) orchestrated\n  by Turbo; MIT-licensed, Docker-ready, GitHub Pages docs.\n\n## Repository layout\n\nThis is a **uv + pnpm monorepo**:\n\n```text\nNovelAI-Image-MCP/\n├── apps/\n│   ├── server/                 # MCP server (the installable PyPI package)\n│   │   ├── src/novelai_image_mcp/   # 11 MCP tools + NovelAI HTTP client\n│   │   ├── tests/\n│   │   ├── docker/              # smoke-test entrypoint\n│   │   ├── Dockerfile           # built with repo root as context\n│   │   └── pyproject.toml       # ruff / pyright / pytest config\n│   └── docs/                    # Sphinx documentation site\n│       ├── source/              # MyST Markdown + conf.py\n│       ├── Makefile\n│       └── pyproject.toml\n├── .github/                     # workflows, CODEOWNERS, issue templates\n├── pyproject.toml               # uv workspace root (virtual)\n├── uv.lock                      # single shared lockfile\n├── pnpm-workspace.yaml          # pnpm workspace declaration\n├── pnpm-lock.yaml               # Node toolchain lockfile\n├── turbo.json                   # cross-workspace task graph\n├── package.json                 # root scripts + dev toolchain\n└── docker-compose.yml           # local container orchestration\n```\n\nSee [`CONTRIBUTING.md`][contributing] for the developer guide and\n[`apps/docs/source/`][docs-source] for the full documentation source.\n\n## Quick start\n\n### Install from source (development)\n\n```bash\n# 1. Clone\ngit clone https://github.com/xinvxueyuan/NovelAI-Image-MCP.git\ncd NovelAI-Image-MCP\n\n# 2. Sync the uv workspace (installs server + docs + dev tools)\nuv sync\n\n# 3. Configure credentials\ncp .env.example .env\n#   set NOVELAI_TOKEN=...  (preferred)\n#   or  NOVELAI_USERNAME + NOVELAI_PASSWORD\n\n# 4. Run (stdio — for local agents)\nuv run python -m novelai_image_mcp serve\n\n# 5. Or over HTTP\nMCP_TRANSPORT=streamable-http uv run python -m novelai_image_mcp serve\n#   → http://127.0.0.1:8000/mcp\n```\n\n### Install from PyPI (runtime only)\n\n```bash\npip install novelai-image-mcp\nexport NOVELAI_TOKEN=pst-...\nnovelai-image-mcp serve\n```\n\n### Optional: Node tooling (contributors)\n\nIf you plan to contribute, install the cross-cutting Node toolchain (turbo,\nhusky, markdownlint) via pnpm:\n\n```bash\ncorepack enable pnpm      # one-time\npnpm install --frozen-lockfile\n```\n\nThis wires the husky pre-commit + commit-msg hooks and gives you `turbo` /\n`markdownlint-cli2` for local development. The MCP server has **zero** Node\nruntime dependencies — this step is only for contributors.\n\n## Connect an agent\n\nThe MCP server supports two transports (stdio + http), all configured under\n`mcpServers`:\n\n### stdio (local agent — Claude Desktop / Cline)\n\n`claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"novelai-image\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/NovelAI-Image-MCP\",\n        \"python\",\n        \"-m\",\n        \"novelai_image_mcp\",\n        \"serve\"\n      ],\n      \"env\": {\n        \"NOVELAI_TOKEN\": \"${input:novelai_token}\"\n      }\n    }\n  }\n}\n```\n\n#### Alternative: uvx (published package)\n\n```json\n{\n  \"mcpServers\": {\n    \"novelai-image\": {\n      \"command\": \"uvx\",\n      \"args\": [\"novelai-image-mcp\", \"serve\"],\n      \"env\": { \"NOVELAI_TOKEN\": \"pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\" }\n    }\n  }\n}\n```\n\nSet `NOVELAI_TOKEN` (or `NOVELAI_USERNAME` + `NOVELAI_PASSWORD`) in the host\nenvironment before launching — `uvx` inherits the parent shell env.\n\n### http (remote / Docker deployment)\n\nAfter `docker compose up --build` (server listens on `http://HOST:8000/mcp`):\n\n```json\n{\n  \"mcpServers\": {\n    \"novelai-image-http\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:8000/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nReplace `http://127.0.0.1:8000/mcp` with your self-deployed endpoint (e.g.\n`https://mcp.example.com/mcp` behind a TLS-terminating reverse proxy). Swap\nthe literal token placeholder for a host-managed secret reference if your\nMCP host supports one (Claude Desktop, Cline, etc. expose this via their\nown secrets UI).\n\n## CLI (sync, for scripting)\n\n```bash\nuv run python -m novelai_image_mcp generate --prompt \"a cat, masterpiece\" --width 832 --height 1216\nuv run python -m novelai_image_mcp upscale --image ./in.png --factor 4\nuv run python -m novelai_image_mcp info          # subscription / Anlas balance\nuv run python -m novelai_image_mcp --help\n```\n\n## Skills (portable agent instructions)\n\nThe project ships three [skills.sh][skills-site] packages that teach AI\nagents (Claude Code, Codex, GitHub Copilot, Cursor, …) how to drive the CLI\nand MCP tools without you pasting docs:\n\n```bash\nnpx skills add --yes --global xinvxueyuan/NovelAI-Image-MCP\n```\n\n| Skill | What it teaches |\n|---|---|\n| `novelai-cli` | Typer CLI commands (serve, generate, upscale, director, annotate, info) for shell scripting |\n| `novelai-mcp-tools` | The 11 MCP tools — model selection, parameters, return shape, Anlas cost |\n| `novelai-workflows` | Multi-step creative pipelines (txt2img→upscale, annotate→img2img, Director edits) |\n\nSkills and the CLI/MCP tools are complementary — install all three and your\nagent picks the right mode based on context. See the\n[Agent skills docs][skills-docs]\nfor details.\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `generate_image` | Text-to-image (V3 / V4 / V4.5 / V5 models, character prompts; vibes V4/V4.5 only) |\n| `image_to_image` | Image-to-image with strength/noise |\n| `inpaint` | Inpainting (requires an inpaint model + mask) |\n| `upscale_image` | 2× / 4× upscale |\n| `director_tool` | Line art / sketch / bg-removal / declutter / colorize / emotion |\n| `annotate_image` | ControlNet annotation (hed, midas, scribble, mlsd, uniformer) |\n| `suggest_tags` | Prompt tag suggestions |\n| `encode_vibe` | Encode a reference image into a vibe token |\n| `get_subscription` | Account subscription + Anlas balance |\n| `get_user_data` | Account user data |\n| `estimate_anlas_cost` | Estimate Anlas cost for a generation (no API call) |\n\nSee the [tools reference][tools-docs]\non the docs site for parameters and examples.\n\n## Configuration\n\nAll settings are environment variables (see `.env.example`). Key ones:\n\n| Variable | Default | Notes |\n|---|---|---|\n| `NOVELAI_TOKEN` | — | Persistent API token (preferred auth) |\n| `NOVELAI_USERNAME` / `NOVELAI_PASSWORD` | — | Access-key login (argon2id) |\n| `NOVELAI_OUTPUT_DIR` | `outputs` | Where generated PNGs are saved |\n| `MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |\n| `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8000` | For streamable-http |\n\nNovelAI API reference: [image.novelai.net/docs][nai-docs]\n\n## Development\n\nThe project is a uv + pnpm monorepo orchestrated by Turbo. See\n[`CONTRIBUTING.md`][contributing] for the full setup; the short version:\n\n```bash\nuv sync                              # Python workspace (server + docs + dev)\npnpm install --frozen-lockfile       # Node toolchain (turbo + husky + markdownlint)\n\npnpm check                           # lint + typecheck + test (all workspaces)\npnpm docs:build                       # build the docs site\npnpm server:serve                     # run the MCP server\npnpm docs:serve                       # sphinx-autobuild with live reload\n```\n\nPer-member commands (via uv):\n\n```bash\nuv run --directory apps/server ruff check src tests    # lint\nuv run --directory apps/server -m pyright              # typecheck\nuv run --directory apps/server -m pytest               # tests\n```\n\n### Docker\n\n```bash\ndocker compose up --build      # builds and runs the server (HTTP transport)\n```\n\nThe Dockerfile lives at [`apps/server/Dockerfile`][dockerfile] but\nthe build context is the repository root (so uv can resolve the workspace\ngraph). See [`docker-compose.yml`][docker-compose].\n\n## Documentation\n\nThe Sphinx documentation site is built with Furo + MyST Markdown and\nauto-deploys to GitHub Pages on every push to `main`:\n\n- **Live site**: [xinvxueyuan.github.io/NovelAI-Image-MCP][docs]\n- **Source**: [`apps/docs/source/`][docs-source]\n- **Build locally**: `pnpm docs:serve`\n\n## License\n\nMIT — see [LICENSE][license]. Per-file SPDX annotations live in\n[REUSE.toml][reuse-toml]. Contributions are subject to the\n[Developer Certificate of Origin][dco] (the `commit-msg` hook signs off\ncommits automatically).\n\n## Links\n\n[ci-badge]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/ci.yml/badge.svg\n[ci-workflow]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/ci.yml\n[docs-badge]: https://github.com/xinvxueyuan/NovelAI-Image-MCP/actions/workflows/docs.yml/badge.svg\n[mit-badge]: https://img.shields.io/badge/License-MIT-blue.svg\n[python-badge]: https://img.shields.io/badge/python-3.13+-blue.svg\n[uv-badge]: https://img.shields.io/badge/uv-managed-261230.svg\n[reuse-badge]: https://api.reuse.software/badge/github.com/xinvxueyuan/NovelAI-Image-MCP\n[deepwiki-badge]: https://deepwiki.com/badge.svg\n[skills-badge]: https://skills.sh/b/xinvxueyuan/NovelAI-Image-MCP\n[product-hunt-badge]: https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1206099&theme=light&t=1784973837616\n[lifto-badge]: https://liftoapp.com/badges/featured-light.svg\n\n[docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/\n[reuse]: https://api.reuse.software/info/github.com/xinvxueyuan/NovelAI-Image-MCP\n[python]: https://www.python.org/downloads/\n[uv]: https://docs.astral.sh/uv/\n[deepwiki]: https://deepwiki.com/xinvxueyuan/NovelAI-Image-MCP\n[skills-sh]: https://skills.sh/xinvxueyuan/NovelAI-Image-MCP\n[product-hunt]: https://www.producthunt.com/products/novelai-image-mcp?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-novelai-image-mcp\n[lifto]: https://liftoapp.com/product/novelai-image-mcp\n[mcp]: https://modelcontextprotocol.io/\n[contributing]: CONTRIBUTING.md\n[docs-source]: apps/docs/source/\n[skills-site]: https://skills.sh\n[skills-docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/skills.html\n[tools-docs]: https://xinvxueyuan.github.io/NovelAI-Image-MCP/tools/index.html\n[nai-docs]: https://image.novelai.net/docs/index.html\n[dockerfile]: apps/server/Dockerfile\n[docker-compose]: docker-compose.yml\n[license]: LICENSE\n[reuse-toml]: REUSE.toml\n[dco]: https://developercertificate.org/\n\n<!-- mcp-name: io.github.xinvxueyuan/novelai-image-mcp -->\n",
  "bytes": 11864,
  "sha": "b59800d9251e5d81984a20f54fe16a845263d51196cbe5e16960a1c315ce2fa1",
  "repo_slug": "xinvxueyuan/novelai-image-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xinvxueyuan_novelai_image_mcp_0e4dad56/readme"
}