WEBTOON Reader MCP
README.md
# WEBTOON Reader MCP
[](https://www.python.org/)
[](https://github.com/jlowin/fastmcp)
[](https://playwright.dev/)
[](LICENSE)
An open-source **MCP (Model Context Protocol) server** for interacting with [WEBTOON](https://www.webtoons.com/) through **FastMCP** and **Playwright**. It enables AI assistants (Claude, Antigravity, OpenCode, and any MCP-compatible client) to search webtoons, read story metadata, list episodes, and open/scroll/screenshot episodes via a managed Chromium browser — all without bypassing any login, payment, age, regional, or anti-bot restrictions.
---
## Features
- 🔍 **Search** public WEBTOON listings by keyword across supported languages
- 📖 **Story metadata** — title, author, description, genre, thumbnail
- 📋 **Episode listing** with pagination support
- 🌐 **Browser-managed episode viewing** using Playwright + Chromium
- 📸 **Viewport screenshots** saved locally
- ↕️ **Scroll control** (up / down) for the open episode page
- 🩺 **Diagnostics tool** to report runtime versions and test connectivity
- ✅ Fully STDIO-based — compatible with any MCP client
> **Legal notice:** This tool only accesses publicly available pages on `www.webtoons.com`. It does not download, cache, or redistribute WEBTOON's copyrighted content. Screenshots are saved locally and are not shared. Use responsibly and in accordance with WEBTOON's [Terms of Service](https://www.webtoons.com/en/terms).
---
## Requirements
| Dependency | Version |
|---|---|
| Python | ≥ 3.11 |
| fastmcp | ≥ 2.14, < 3 |
| playwright | ≥ 1.50, < 2 |
| requests | ≥ 2.32, < 3 |
| beautifulsoup4 | ≥ 4.12, < 5 |
---
## Installation
### 1. Clone the repository
```bash
git clone https://github.com/abhishekxkumar78-sys/webtoon-reader-mcp.git
cd webtoon-reader-mcp
```
### 2. Create a virtual environment and install dependencies
```bash
# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### 3. Install Playwright's Chromium browser
```bash
# Windows
.venv\Scripts\playwright install chromium
# macOS / Linux
.venv/bin/playwright install chromium
```
---
## Running the server
### Windows (batch file — easiest)
Create a `start_server.bat` in the project root:
```bat
@echo off
setlocal
cd /d "%~dp0"
"%~dp0.venv\Scripts\python.exe" "%~dp0server.py"
```
Then double-click it, or run from PowerShell:
```powershell
.\start_server.bat
```
### Manual (PowerShell)
```powershell
.venv\Scripts\python.exe server.py
```
### macOS / Linux
```bash
.venv/bin/python server.py
```
The server communicates over **STDIO** (standard input/output). Do not run it in a terminal that prints extra text to stdout, as that will break the MCP protocol framing.
---
## MCP Client Configuration
### Antigravity / Gemini
Add to your MCP JSON configuration (replace paths with your actual installation path):
```json
{
"mcpServers": {
"webtoon-reader": {
"command": "/absolute/path/to/webtoon-reader-mcp/.venv/Scripts/python.exe",
"args": ["/absolute/path/to/webtoon-reader-mcp/server.py"]
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"webtoon-reader": {
"command": "/absolute/path/to/webtoon-reader-mcp/.venv/Scripts/python.exe",
"args": ["/absolute/path/to/webtoon-reader-mcp/server.py"]
}
}
}
```
### OpenCode
Add to `opencode.json`:
```json
{
"mcp": {
"webtoon-reader": {
"type": "local",
"command": [
"/absolute/path/to/webtoon-reader-mcp/.venv/Scripts/python.exe",
"/absolute/path/to/webtoon-reader-mcp/server.py"
],
"enabled": true
}
}
}
```
> **Note for Windows users:** Use double backslashes (`\\`) or forward slashes (`/`) in JSON paths.
---
## Available Tools
| Tool | Type | Description |
|---|---|---|
| `search_webtoons` | sync | Search public WEBTOON listings by keyword |
| `get_story_details` | sync | Read metadata from a WEBTOON story page |
| `list_episodes` | sync | List episodes for a story with pagination |
| `open_episode` | async | Open an episode URL in the managed Chromium browser |
| `current_episode_info` | async | Describe the currently open page |
| `scroll_episode_viewport` | async | Scroll the open episode up or down by ~75% of viewport height |
| `screenshot_current_viewport` | async | Save a viewport-only PNG screenshot to `screenshots/` |
| `close_webtoon_browser` | async | Close the Playwright-managed browser |
| `diagnose_browser_launch` | async | Report runtime versions and test a basic navigation |
### Tool details
#### `search_webtoons(query, language="en", limit=10)`
Searches public WEBTOON listings. `language` accepts short codes like `"en"`, `"fr"`, `"es"`, `"de"`, `"th"`, `"id"`, `"zh-hant"`, `"zh-hans"`. `limit` is capped at 50.
#### `get_story_details(story_url)`
`story_url` must be a public `https://www.webtoons.com/*/list?title_no=*` URL.
#### `list_episodes(story_url, page=1)`
Returns an array of episode objects. Use `page` to paginate.
#### `open_episode(episode_url)`
Navigates the managed browser to the given `https://www.webtoons.com/*/viewer?*` URL. Includes one automatic crash-recovery attempt.
#### `scroll_episode_viewport(direction)`
`direction` is `"up"` or `"down"`.
#### `screenshot_current_viewport(filename=None)`
If `filename` is omitted, a timestamped name is used. Files are saved to `screenshots/` and never overwrite existing files.
#### `diagnose_browser_launch()`
Returns `python_version`, `fastmcp_version`, `playwright_version`, `browser_version`, `launch_success`, and `navigation_success`.
---
## Project Structure
```
webtoon-reader-mcp/
├── server.py # FastMCP server — all 9 MCP tools
├── requirements.txt # Pinned dependency ranges
├── logs/ # Runtime log directory (server.log created on startup)
├── screenshots/ # Viewport screenshots saved by screenshot_current_viewport
├── .gitignore
├── LICENSE # MIT
└── README.md
```
---
## Security & Privacy
- Only public `www.webtoons.com` URLs are accessed; the URL is validated before every HTTP request and before every Playwright navigation.
- No login credentials, cookies, or session tokens are stored or transmitted.
- Screenshots are saved to your local `screenshots/` directory only; they are listed in `.gitignore` and are never committed.
- Logs are written to `logs/server.log` (also in `.gitignore`).
- The server holds exactly one Chromium browser instance per process lifetime and disposes it cleanly on exit.
---
## Development & Testing
### Verify syntax
```bash
python -m py_compile server.py
```
### Smoke-test the STDIO protocol
You can write a minimal MCP client that sends `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}` over stdin and reads the response from stdout.
### Linting (optional)
```bash
pip install ruff
ruff check server.py
```
---
## Contributing
Contributions are welcome! Please follow these guidelines:
1. **Fork** the repository and create a feature branch (`git checkout -b feat/my-feature`).
2. Keep changes focused — one feature or fix per PR.
3. Do **not** commit credentials, API keys, `integration-results.json`, or personal config files. The `.gitignore` already excludes them.
4. Do **not** add tools that bypass WEBTOON's access controls (login walls, age gates, regional restrictions).
5. Run `python -m py_compile server.py` before opening a PR.
6. Open a [GitHub Issue](../../issues) first for significant changes so we can discuss the approach.
---
## Disclaimer
This project is an independent open-source tool and is **not affiliated with, endorsed by, or sponsored by WEBTOON** or LINE Corporation. WEBTOON® is a registered trademark of WEBTOON Entertainment Inc. All WEBTOON content is the property of its respective creators and publishers. This tool interacts only with publicly accessible pages in the same manner as a web browser.