# ?? Suwayomi MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![MCP Standard](https://img.shields.io/badge/MCP-1.0%20%2F%202.0-00f2fe.svg)](https://modelcontextprotocol.io/)
[![Suwayomi-Server](https://img.shields.io/badge/Suwayomi-v2.0+-purple.svg)](https://github.com/Suwayomi/Suwayomi-Server)

A high-performance **Model Context Protocol (MCP)** server that connects AI coding assistants and autonomous agents (**Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Antigravity**) directly to your self-hosted [Suwayomi-Server](https://github.com/Suwayomi/Suwayomi-Server) manga and manhwa library.

---

## ? The Problem & The Solution

### The Bottleneck
Manga, manhwa, and light-novel enthusiasts often manage hundreds of titles and thousands of chapters across multiple extension sources (MangaDex, Webtoons, Asura, Flame, etc.). 

Until now, using AI agents to manage this collection was fractured:
* **Mobile Mihon/Tachiyomi** has no exposed API, requiring brittle static backup parsing (`.tachibk`) that cannot execute live searches, write changes, or download chapters.
* **Aggregator UIs** require manual searching, clicking across 5+ extension tabs, and manually queueing chapter updates.

### The Solution
`suwayomi-mcp` bridges the gap. By communicating directly with Suwayomi’s local GraphQL engine over standard JSON-RPC (stdio transport), your AI assistant can:
1. **Audit your library state** in real time (tracking unread chapter backlogs, completion status, and genres).
2. **Execute instant full-text searches** across your database and batch-add titles to your favorites.
3. **Queue and trigger background chapter downloads** with a single natural language sentence.

---

## ??? System Architecture

```
+-------------------------------------------------------------------------+
|                         LLM / AI ASSISTANT                              |
|           (Claude Desktop, Claude Code, Cursor, Windsurf)               |
+-------------------------------------------------------------------------+
                                     ¦  (Natural Language Intent)
                                     ?
+-------------------------------------------------------------------------+
|                  SUWAYOMI MCP SERVER (FastMCP / Python)                 |
|  • suwayomi_get_library       • suwayomi_search_and_add                 |
|  • suwayomi_download_chapters • suwayomi_get_download_status            |
+-------------------------------------------------------------------------+
                                     ¦  (GraphQL POST JSON / stdio)
                                     ?
+-------------------------------------------------------------------------+
|                  SUWAYOMI-SERVER DAEMON (localhost:4567)                |
|  • GraphQL Resolver           • H2 Database (Library & Metadata)        |
|  • Source Scrapers            • Chapter Downloader Worker               |
+-------------------------------------------------------------------------+
```

---

## ??? Tool Suite & Real-World Prompts

| Tool | Signature | What You Ask In Chat |
| :--- | :--- | :--- |
| `suwayomi_get_library` | `(in_library_only=True, search=None, limit=50)` | *"Which manga in my library currently have more than 100 unread chapters?"* |
| `suwayomi_search_and_add` | `(query, auto_add_first=False, limit=20)` | *"Find 'Latna Saga' in my database and add it to my favorites."* |
| `suwayomi_download_chapters` | `(manga_id, count=5, unread_only=True, chapter_ids=None)` | *"Download the next 5 unread chapters of Hand Jumper."* |
| `suwayomi_get_download_status` | `()` | *"Check if the Suwayomi chapter downloader is still running."* |

---

## ?? Prerequisites

1. **[Suwayomi-Server](https://github.com/Suwayomi/Suwayomi-Server)** installed and running locally on port `4567` (default endpoint: `http://127.0.0.1:4567/api/graphql`).
2. **Python 3.10+** installed on your system.

---

## ?? Installation Guide

### ?? Windows Setup (PowerShell)

```powershell
# 1. Clone repository
git clone https://github.com/augumenter/suwayomi-mcp.git
cd suwayomi-mcp

# 2. Create and activate virtual environment
python -m venv .venv
.\.venv\Scripts\activate

# 3. Install in editable mode
pip install -e .

# 4. Run automated test suite to verify live connectivity
pytest tests -v
```

---

### ?? macOS Setup (Terminal / zsh)

```bash
# 1. Clone repository
git clone https://github.com/augumenter/suwayomi-mcp.git
cd suwayomi-mcp

# 2. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install in editable mode
pip install -e .

# 4. Run automated test suite
pytest tests -v
```

---

### ?? Linux / Docker Setup (Ubuntu / Debian / Arch)

```bash
# 1. Clone repository
git clone https://github.com/augumenter/suwayomi-mcp.git
cd suwayomi-mcp

# 2. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install package
pip install -e .

# 4. Run tests
pytest tests -v
```

---

## ?? AI Client Configuration

### 1. Claude Desktop

Add this to your `claude_desktop_config.json`:

* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "suwayomi": {
      "command": "C:\\path\\to\\suwayomi-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\suwayomi-mcp",
      "env": {
        "SUWAYOMI_GRAPHQL_URL": "http://127.0.0.1:4567/api/graphql"
      }
    }
  }
}
```
*(On macOS/Linux, replace `command` with `/path/to/suwayomi-mcp/.venv/bin/python`)*

---

### 2. Claude Code CLI (`~/.claude.json`)

```json
{
  "mcpServers": {
    "suwayomi": {
      "command": "C:\\path\\to\\suwayomi-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\suwayomi-mcp",
      "env": {
        "SUWAYOMI_GRAPHQL_URL": "http://127.0.0.1:4567/api/graphql"
      }
    }
  }
}
```

---

### 3. Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "suwayomi": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "SUWAYOMI_GRAPHQL_URL": "http://127.0.0.1:4567/api/graphql"
      }
    }
  }
}
```

---

## ?? Real-World Conversation Examples

### Example 1: Library Audit & Recommendations
```text
User: "Check my library and recommend something intense to read from my unread backlog."

Agent: "I checked your Suwayomi library. Here are your top unread thriller & action series:
1. Hand Jumper (130 unread chapters) - Thriller / Supernatural
2. Psychopath in Murim (30 unread chapters) - Action / Fantasy
3. Lookism (1,237 unread chapters) - Action / Delinquents

Would you like me to queue the next 5 chapters of Hand Jumper for offline reading?"
```

### Example 2: Automatic Title Ingestion
```text
User: "Find Latna Saga and make sure it is added to my library favorites."

Agent: "Found 'Latna Saga: Survival of a Sword King' (ID: 38).
I executed the updateManga mutation and set inLibrary: true. It is now tracked in your favorites."
```

### Example 3: Batch Chapter Downloading
```text
User: "Download the next 10 unread chapters of Omniscient Reader."

Agent: "Fetched unread chapter IDs [412, 413, 414, 415, 416, 417, 418, 419, 420, 421].
Dispatched enqueueChapterDownloads mutation and triggered the downloader daemon.
Download status: STARTED (10 items in queue)."
```

---

## ?? Interactive Neural Network Visualizer

This project includes a real-time animated **Neural Synaptic Graph** that visualizes packet transit across every layer of the MCP bridge.

To launch the visualizer:
```bash
python -m http.server 8080 --directory visualizer
```
Open **`http://localhost:8080`** in your browser to interact with kinetic nodes, fire synaptic pulse sequences, and inspect live payload telemetry.

---

## ?? Troubleshooting & FAQ

#### `Unable to connect to remote server (127.0.0.1:4567)`
* **Cause**: Suwayomi-Server is not running.
* **Fix**: Start your local Suwayomi daemon (`Suwayomi Launcher.bat` on Windows or `suwayomi-server` via terminal) and verify `http://localhost:4567` loads in your browser.

#### `GraphQL Errors: Missing source`
* **Cause**: The manga was imported from an extension that is currently disabled or uninstalled.
* **Fix**: Open Suwayomi WebUI -> Browse -> Extensions, and ensure the corresponding extension is installed and updated.

---

## ?? License

MIT License. Copyright (c) 2026 Ileri Nwajei ([@augumenter](https://x.com/augumenter)).