+-------------------------------------------------------------------------+
|                         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               |
+-------------------------------------------------------------------------+

# 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

# 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

# 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

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

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

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

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

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

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

python -m http.server 8080 --directory visualizer