Skip to main content
Glama
ComicK MCP Server

ComicK MCP Server

by edmer664

ComicK MCP Server (comick-mcp)

License: MIT Python 3.10+ MCP Protocol

An open-source Model Context Protocol (MCP) server connecting any AI coding agent or desktop assistant directly to the ComicK (comick.dev) manga, manhwa, and manhua database—with natural-language trope parsing, verified tag matching, and multi-mirror failover.

Demo Video (60s): Watch demo.mp4 (generated programmatically with HyperFrames + Gemini TTS) or explore the composition source in video-demo/.


Fast-Copy Agent Installation

Copy the prompt below and paste it directly into your AI coding agent (Antigravity, Claude Code, Cursor, Windsurf, Cline, or Codex) to clone, install, test, and register comick-mcp automatically:

Install and configure the ComicK MCP server (https://github.com/edmer664/comick-mcp) in my environment:

1. Ensure Python >= 3.10 and Git are available. Clone `https://github.com/edmer664/comick-mcp.git` into a clean local directory (such as `~/.local/share/comick-mcp` on macOS/Linux, `%USERPROFILE%\.local\share\comick-mcp` on Windows, or `./comick-mcp` inside the current workspace).
2. Inside the cloned directory, create a Python virtual environment `.venv` and install the package with `<venv-python> -m pip install -e .`.
3. Register the `"comick"` stdio MCP server in my active agent MCP config using the full path to the `.venv` Python interpreter and `server.py`:
   - command: "<absolute path to .venv python executable>"
   - args: ["<absolute path to comick-mcp/server.py>"]
   - env: {"PYTHONIOENCODING": "utf-8", "PYTHONUNBUFFERED": "1"}
   (Targets: Antigravity `~/.gemini/config/mcp_config.json` or workspace `.mcp.json`, Claude Code `.mcp.json` / `claude mcp add`, Cursor `~/.cursor/mcp.json`, Windsurf `~/.codeium/windsurf/mcp_config.json`.)
4. Run `<venv-python> test_mcp.py` inside the `comick-mcp` folder and confirm all checks pass, then report the install path and registered config file.

Related MCP server: JMComic AI

Key Features

  • Natural-Language Discovery: Ask "I want a badass MC manhwa with swords and magic" and comick-mcp extracts origin (kr -> Manhwa), genres (action, fantasy, magic), and category tropes (overpowered-protagonist, sword-and-sorcery, reincarnation), running multi-pass queries sorted by popularity and relevance.

  • Verified Taxonomy Cache: Automatically indexes ComicK's genre list and MangaUpdates category tags in a local taxonomy_cache.json (7-day TTL) for fuzzy slug matching.

  • Resilient API Routing: Automatically fails over between api.comick.dev, comick-api-proxy.notaspider.dev/api, and legacy endpoints if an upstream mirror rate-limits or blocks automated traffic.

  • Zero Auth Required: Works out of the box with no ComicK API keys.


Available MCP Tools

Tool

Purpose

search_comics

Search using natural-language prompts or explicit filters (genres, tags, country, status, demographic, sort, min_chapters, excluded_genres, excluded_tags).

recommend_comics_by_prompt

Conversational recommendation engine with multi-pass search, concurrent MangaUpdates category verification, and relevance scoring.

get_comic_details

Retrieve full series metadata, alt titles, synopsis, genres, MangaUpdates tags, creators, ratings, and recommendations by slug or hid.

get_comic_chapters

List translated chapters with language filters and pagination.

get_trending_comics

Fetch trending, newly followed, or top-followed manhwa, manga, or manhua over 7, 30, 90, or 180 days.

search_genres_and_tags

Look up exact ComicK genre and tag slugs by keyword.


Manual Installation

1. Clone and install

git clone https://github.com/edmer664/comick-mcp.git
cd comick-mcp
python -m venv .venv

# Windows (PowerShell):
.venv\Scripts\Activate.ps1
# macOS / Linux:
# source .venv/bin/activate

pip install -e .

2. Configure your MCP client

Add "comick" to .mcp.json (project-scoped) or your client's global MCP config (~/.gemini/config/mcp_config.json, ~/.cursor/mcp.json, ~/.claude.json):

{
  "mcpServers": {
    "comick": {
      "command": "/absolute/path/to/comick-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/comick-mcp/server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

On Windows, replace .venv/bin/python with C:\\path\\to\\comick-mcp\\.venv\\Scripts\\python.exe and use Windows paths in args.


Verification

Run the included end-to-end suite to verify natural-language search, API/mirror connectivity, taxonomy lookup, and a live stdio MCP client handshake:

python test_mcp.py

Project Structure

  • server.py — MCPServer("comick") entrypoint registering the 6 stdio MCP tools.

  • comick_client.py — Resilient ComicK client, taxonomy cache manager, trope parser, and multi-pass relevance scorer.

  • test_mcp.py — End-to-end tool & stdio JSON-RPC verification script.

  • video-demo/ — HyperFrames + Gemini TTS 60-second demo project and asset generator.

  • CONTRIBUTING.md — Guide for extending trope rules, endpoints, and tests.

License

Released under the MIT License.

Available Tools

6 tools
get_comic_chaptersA

List chapters for a comic on ComicK. Accepts either the comic's slug or hid.

Args: comic_id_or_slug: Comic slug or hid (auto-resolves slug to hid). lang: Language code filter (default "en"; comma-separated like "en,fr" or empty for all). page: 1-based page number (default 1). limit: Chapters per page (default 30, max 100).

Inputs: comic_id_or_slug (required), lang, page, limit. Returns: result

get_comic_detailsA

Retrieve full metadata, synopsis, genres, verified MangaUpdates tags/categories, authors, artists, ratings, and similar comic recommendations for a ComicK entry.

Args: comic_id_or_slug: Comic slug (e.g. "01-survival-story-of-a-sword-king-in-a-fantasy-world") or hid (e.g. "Qy66f_CI").

Inputs: comic_id_or_slug (required). Returns: result

recommend_comics_by_promptA

Recommend comics from ComicK for a conversational user request such as "I want a badass MC manhwa with swords and magic".

Runs multi-pass trope and genre searches, verifies MangaUpdates category tags on top candidates, scores relevance against genres, verified tags, synopses, ratings, and follower counts, and returns rich recommendations with explanations.

Args: prompt: Natural-language request describing what the user wants to read. limit: Number of recommendations to return (default 10, max 25). min_chapters: Optional minimum chapter count filter (e.g. 50). status: Optional publication status filter ('ongoing', 'completed', 'hiatus', 'cancelled').

Inputs: prompt (required), limit, status, min_chapters. Returns: result

search_comicsA

Search the ComicK database using a natural-language query, title keyword, or structured filters.

Natural-language descriptions (e.g., "I want a badass MC manhwa with swords and magic") are automatically parsed into country ('kr'/'jp'/'cn'), genres, category tags, status, and sort filters and executed across multi-pass queries so you get relevant ranked matches instead of zero literal-title matches.

Args: query: Natural-language description (e.g. "I want a badass MC manhwa with swords and magic") or comic title (e.g. "Solo Leveling"). genres: Comma-separated genre slugs (e.g. "action,fantasy,magic,martial-arts"). tags: Comma-separated category/tag slugs (e.g. "sword-and-sorcery-magic,overpowered-protagonist,swordsman"). country: Comma-separated origin codes or names ('kr' / 'manhwa', 'jp' / 'manga', 'cn' / 'manhua'). status: Publication status ('ongoing'/'1', 'completed'/'2', 'cancelled'/'3', 'hiatus'/'4'). demographic: Comma-separated demographics ('shounen'/'1', 'shoujo'/'2', 'seinen'/'3', 'josei'/'4'). sort: Sort field ('user_follow_count'/'popular', 'rating', 'average_rating', 'view', 'uploaded', 'created_at'). min_chapters: Minimum chapter count (e.g. 50). excluded_genres: Comma-separated genre slugs to exclude. excluded_tags: Comma-separated category/tag slugs to exclude. page: 1-based pagination page (default 1). limit: Max results to return (default 15, max 50).

Inputs: page, sort, tags, limit, +8 more. Returns: result

search_genres_and_tagsA

Search ComicK's official genres and category tags by keyword to find exact filter slugs.

Args: keyword: Substring to match against genre/tag names and slugs (e.g. "sword", "magic", "protagonist"). Leave empty for top genres/tags. limit: Max genres and max tags to return (default 50).

Inputs: limit, keyword. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation3/5

    search_comics and recommend_comics_by_prompt both accept natural-language input and return ranked comic lists, so an agent must read carefully to pick between 'structured search that parses NL into filters' and 'multi-pass recommendation with explanations'. The remaining tools (details, chapters, trending, genre/tag lookup) are cleanly distinct.

    Naming Consistency5/5

    All six tools follow a consistent snake_case verb_noun pattern (search_comics, get_comic_details, get_comic_chapters, get_trending_comics, search_genres_and_tags). recommend_comics_by_prompt is longer but still obeys the same verb-first convention.

    Tool Count5/5

    Six tools is well within the ideal range and each maps to a distinct step in the discovery workflow: find slugs, search, recommend, inspect, list chapters, browse trending. No tool feels redundant padding.

    Completeness4/5

    The discovery lifecycle is well covered: filter discovery, search, recommendation, details (including similar comics), chapter listing, and trending rankings. Minor gaps remain, such as no pagination cursor exposed on trending and no way to retrieve chapter page content or reader links, but the stated search/discovery purpose is largely satisfied.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage a self-hosted Suwayomi manga library through natural language, including searching, adding titles, and downloading chapters.
      4
      2
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search, browse, and download manga albums, chapters, and covers, view comments and rankings, manage favorites and account login, and convert downloaded content into ZIP, PDF, or long images. Also supports background task control with progress reporting, cancellation and retry, runtime configuration updates, and diagnostic resources for domain and environment checks.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search and filter titles, browse rankings, read comments, manage favorites, download albums, chapters, and covers with live progress, cancellation, and retry, and convert downloads into ZIP, PDF, or long images, all through natural language. Exposes 21 tools and 3 knowledge resources over stdio, SSE, and HTTP transports, along with runtime configuration and account login.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search, browse rankings, view album details and comments, manage favorites, and download manga albums or individual chapters asynchronously with progress tracking, cancellation, and retry. Also supports post-processing downloads into ZIP/PDF/long images, dynamic configuration updates, account login with cookie persistence, and access to schema/reference knowledge resources over stdio, SSE, and HTTP transports.
      -