?? Suwayomi MCP 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 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 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)

# 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)

# 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)

# 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

{
  "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)

{
  "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)

{
  "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

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

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

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:

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).