Metadata-Version: 2.5
Name: mangacutter-mcp
Version: 0.1.0
Summary: MCP server for MangaCutter: cut manga pages into panels and characters into parts from Claude, Cursor and other AI apps.
Project-URL: Homepage, https://mangacutter.com
Author: MangaCutter
License: Proprietary
Keywords: claude,comics,manga,mcp,panels,segmentation
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pillow>=10.4
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# MangaCutter MCP

Use [MangaCutter](https://mangacutter.com) from Claude, Cursor and other AI apps that support MCP.

Ask in plain language, for example:

- "Cut the panels of the pages in `C:\Manga\ch12`, Japanese manga"
- "Separate the hair, face and clothes of the character in `~/art/cover.png`"
- "How many credits do I have?"

The AI looks at small previews of your pages, picks the options, tells you the cost and,
after your OK, the cuts are saved to a folder on your computer.

The server runs **on your computer**. It reads the pages from disk and sends them straight
to the MangaCutter API. The images do not go through the AI conversation, except the small
previews the AI asks for to choose the options. That is what makes whole chapters practical.

## Requirements

- A MangaCutter **Pro** or **Enterprise** plan.
- An API key: MangaCutter, **Settings**, section **API and MCP**, **Create key**.
- [uv](https://docs.astral.sh/uv/getting-started/installation/), which downloads and runs this package.

## Install

### Claude Desktop

Settings, Developer, Edit config. Put this in `claude_desktop_config.json` and restart Claude.
If `mcpServers` already lists other servers, add only the `mangacutter` block next to them:

```json
{
  "mcpServers": {
    "mangacutter": {
      "command": "uvx",
      "args": ["mangacutter-mcp"],
      "env": { "MANGACUTTER_API_KEY": "mc_live_..." }
    }
  }
}
```

### Claude Code

```bash
claude mcp add --transport stdio --scope user --env MANGACUTTER_API_KEY=mc_live_... mangacutter -- uvx mangacutter-mcp
```

### Cursor

Add the same `mangacutter` block inside `mcpServers` in `~/.cursor/mcp.json` and restart Cursor.

## What it can do

| Tool | Cost | What it does |
|---|---|---|
| `get_account` | free | Plan, credits and how many pages run at the same time |
| `list_images` | free | Pages in a folder, in reading order (p2 before p10), and the cost |
| `preview_images` | free | Small previews (up to 6) so the AI can choose the options |
| `cut_panels` | 1 credit/page | Cuts pages into `panel_01.png`, `panel_02.png`... + `page_full.png` + `manifest.json` |
| `cut_character` | 1 credit/image | One transparent PNG per part + `rest.png` + `manifest.json` |
| `batch_status` | free | Progress of a batch |
| `resume_batch` | only new pages | Continues a batch that stopped |
| `cancel_batch` | free | Stops sending new pages |
| `list_batches` | free | Recent batches, if the batch id was lost |
| `list_jobs` / `download_job` | free | Jobs on your account, including ones made on the website |

Two prompts are included as shortcuts: **Cut a chapter into panels** and
**Separate a character into parts**.

## Credits and safety

- Every cutting call has a required `max_credits`. The call is refused if the pages would
  cost more, and the AI is instructed to confirm the cost with you first.
- **Never pays twice for the same page.** Each page is sent with a key derived from its
  content and options. Running the same pages with the same options again reuses the
  previous result for free. A crash, a lost connection or `resume_batch` never charges again
  for a page that was already sent.
- Pages that fail on MangaCutter's side are refunded automatically.
- Results are saved to a `mangacutter` folder next to your pages (or the folder you choose).
  Existing files are never overwritten: a new folder gets a ` (2)` suffix.
- Only image files (PNG, JPG, WebP up to 10 MB) are ever read and sent. Other files in the
  folder are ignored and never leave your computer.
- The API key can only cut pages and read your balance and job history. It cannot change
  your account or subscription. If it leaks, revoke it in Settings.

## Batches keep running

A batch runs in the background while your AI app is open, so long chapters do not block
the conversation. Its state is saved in `<output folder>/.mangacutter/<batch id>.json`
after every page. If the app is closed in the middle, ask the AI to resume the batch: pages
already sent are downloaded without being charged again.

## Configuration

| Variable | Default | |
|---|---|---|
| `MANGACUTTER_API_KEY` | (required) | Your key, starts with `mc_live_` |
| `MANGACUTTER_API_URL` | `https://api.mangacutter.com/api/v1` | Only for testing |
| `MANGACUTTER_HOME` | `~/.mangacutter` | Where the list of recent batches is kept |

## Troubleshooting

- **"MANGACUTTER_API_KEY is not set"**: the key is missing from the `env` block of the config.
- **"rejected the API key"**: the key was revoked or mistyped. Create a new one in Settings.
- **"plan does not include the API"**: the API and MCP are part of Pro and Enterprise.
- **`uvx` not found**: install uv and restart the AI app.

---

## Em português

Use o MangaCutter pelo Claude, Cursor e outros apps de IA com MCP. Peça, por exemplo,
"corta os quadros das páginas da pasta `C:\Mangas\cap12`, mangá japonês". A IA olha
miniaturas das páginas, escolhe as opções, mostra o custo e, depois do seu OK, os recortes
caem numa pasta do seu PC.

Precisa do plano **Pro** ou **Enterprise**, de uma chave (Configurações, **API e MCP**) e do
[uv](https://docs.astral.sh/uv/getting-started/installation/). A instalação é a mesma das
seções acima. Cada página custa 1 crédito, a mesma página com as mesmas opções nunca é
cobrada duas vezes, e um lote interrompido continua de onde parou sem cobrar de novo.
