Content
# Kakuyomu MCP Server
This is an MCP (Model Context Protocol) server for reading content from the novel posting site "[カクヨム](https://kakuyomu.jp/)". It provides tools for LLM agents to search for works, retrieve episode lists, and read text from Kakuyomu.
## Features
- **Work Search**: Keyword search and detailed filtering (genre, number of reviews, character count, publication date, etc.)
- **Top Page Retrieval**: Get a list of the latest works
- **Episode List**: Retrieve episode information for a specific work
- **Text Retrieval**: Get the text of a specific episode
## 🚀 Try it out easily
You can quickly try it out using the image published on [Docker Hub](https://hub.docker.com/r/ubiq/kakuyomu-mcp).
### Using with Claude Code
```bash
# Pull from Docker Hub
docker pull ubiq/kakuyomu-mcp:latest
# Add to Claude Code settings
claude mcp add kakuyomu-mcp -- docker run -i --rm ubiq/kakuyomu-mcp:latest
# Start
claude
```
### Using with Claude Desktop
```bash
# Pull from Docker Hub
docker pull ubiq/kakuyomu-mcp:latest
```
Add the following to `claude_desktop_config.json` and restart Claude Desktop:
```json
{
"mcpServers": {
"kakuyomu_mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"ubiq/kakuyomu-mcp:latest"
],
"env": {}
}
}
}
```
## Installation
### Required Environment
- Python 3.10 or higher
- Poetry
### Setup
```bash
# Clone the repository
git clone https://github.com/106-/kakuyomu-mcp.git
cd kakuyomu-mcp
# Install dependencies
poetry install
```
## Usage
### Starting the Server
```bash
# Run directly
make run
```
### Running with Docker
```bash
# Run in a Docker container
make docker-run
```
### Using with Claude Code (MCP)
Add the following configuration to the `.mcp.json` file:
```json
{
"mcpServers": {
"kakuyomu_mcp": {
"type": "stdio",
"command": "poetry",
"args": [
"run",
"python",
"./kakuyomu_mcp/main.py"
],
"env": {}
}
}
}
```
If using Docker:
```json
{
"mcpServers": {
"kakuyomu_mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"kakuyomu-mcp"
],
"env": {}
}
}
}
```
## Available Tools
### 1. `get_top_page`
Retrieve the list of the latest works from the top page.
**Parameters:**
- `limit` (optional): The maximum number of works to retrieve (default: 10)
### 2. `search_works`
Search for works using keywords.
**Parameters:**
- `q` (required): Search keyword
- `page` (optional): Page number (default: 1)
- `ex_q` (optional): Exclusion keyword
- `serial_status` (optional): Serialization status ("running", "completed")
- `genre_name` (optional): Genre ("fantasy", "action", "sf", etc.)
- `total_review_point_range` (optional): Range of review points
- `total_character_count_range` (optional): Range of character counts
- `published_date_range` (optional): Range of publication dates
- `last_episode_published_date_range` (optional): Range of last episode publication dates
- `limit` (optional): The maximum number of works to retrieve (default: 10)
### 3. `get_work_episodes`
Retrieve the episode list for a specific work.
**Parameters:**
- `work_id` (required): Work ID
- `limit` (optional): The maximum number of episodes to retrieve (default: 20)
### 4. `get_episode_content`
Retrieve the text of a specific episode.
**Parameters:**
- `work_id` (required): Work ID
- `episode_id` (required): Episode ID
## Development
### Setting Up the Development Environment
```bash
# Install including development dependencies
poetry install --with dev
```
### Project Structure
```
kakuyomu-mcp/
├── kakuyomu_mcp/
│ ├── __init__.py
│ └── main.py # Main implementation of the MCP server
├── kakuyomu.ipynb # Implementation examples and test cases
├── pyproject.toml # Project configuration
├── poetry.lock # Dependency lock
├── CLAUDE.md # Development guide for Claude Code
└── README.md # This file
```
## Example of Operation
```
> Choose a suitable work from the top page of Kakuyomu and summarize the first 5 episodes.
● The task is to select a work from the top page of Kakuyomu and read the first 5 episodes to summarize. First, organize the tasks before executing.
● Update Todos
⎿ ☐ Retrieve the list of works from the top page of Kakuyomu
☐ Select a suitable work
☐ Retrieve the episode list of the selected work
☐ Read the text of the first 5 episodes
☐ Summarize and report the content read
● First, retrieve the works from the top page of Kakuyomu.
● Update Todos
⎿ ☐ Retrieve the list of works from the top page of Kakuyomu
☐ Select a suitable work
☐ Retrieve the episode list of the selected work
☐ Read the text of the first 5 episodes
☐ Summarize and report the content read
● kakuyomu_mcp:get_top_page (MCP)(limit: 10)…
⎿ ID: 16816700429146389370
Title: 【2/26コミカライズ１巻＆3/24書籍３巻発売！】鈴の蕾は龍に抱かれ花ひらく ～迷子宮女と美貌の宦官の後宮事件帳～【WEB版】
… +36 lines (ctrl+r to expand)
Catchphrase: All the annoying bosses get what they deserve! The strongest magician reincarnated is on a rampage!
● Successfully retrieved the list of works from the top page. Now, choose an interesting work. I will select a work with the unique title "It seems like an unknown girl is doing housework at home. But she was cute, so I'm keeping an eye on her."
● Update Todos
⎿ ☒ Retrieved the list of works from the top page of Kakuyomu
☐ Select a suitable work
☐ Retrieve the episode list of the selected work
☐ Read the text of the first 5 episodes
☐ Summarize and report the content read
● kakuyomu_mcp:get_work_episodes (MCP)(work_id: "16817330651584484057", limit: 10)…
⎿ ID: 16817330651584506895
Title: Episode 1: Probably Silky
… +36 lines (ctrl+r to expand)
Publication Date: 2023-07-13T09:00:16Z
● Wonderful! Successfully retrieved the episode list. Now I'm ready to read the text of the first 5 episodes.
● Update Todos
⎿ ☒ Retrieved the list of works from the top page of Kakuyomu
☒ Selected a suitable work
☒ Retrieved the episode list of the selected work
☐ Read the text of the first 5 episodes
☐ Summarize and report the content read
● Now, I will read the text of the first 5 episodes in parallel.
● kakuyomu_mcp:get_episode_content (MCP)(work_id: "16817330651584484057", episode_id: "16817330651584506895")…
⎿ As a university student, I often go out to eat with friends. Sometimes friends bring their friends, and before I know it, I'm dining with strangers.
"──Ah, hello. I'm Haruto Mizuki. I've known Yosuke since high school."
… +41 lines (ctrl+r to expand)
"But reacting now feels a bit annoying, and having someone do housework for me is genuinely helpful, so I've been turning a blind eye to that stalker, thinking of them as the fairy Silky."
"Why the hell!?"
● kakuyomu_mcp:get_episode_content (MCP)(work_id: "16817330651584484057", episode_id: "16817330651584506895")…
⎿ ──It was a scary story I provided as a snack for drinks, but it seemed to have stirred up more fear than expected, and I received a stern lecture from both of them.
"Hmm..."
… +69 lines (ctrl+r to expand)
"I don't get it..."
──In the end, I couldn't narrow down the candidates no matter how much I thought about it that day.
● kakuyomu_mcp:get_episode_content (MCP)(work_id: "16817330651584484057", episode_id: "16817330651584506895")…
⎿ "Mizuki-kun. This is for table three."
"Okay!"
… +78 lines (ctrl+r to expand)
Well, it would be awkward to go back and ask now, so I might as well give up. I decided to wrestle with the peak time, which I had no idea when it would end.
──But seriously, who is that stalker?
● kakuyomu_mcp:get_episode_content (MCP)(work_id: "16817330651584484057", episode_id: "16817330651584506895")…
⎿ University is a place where you have much more freedom compared to previous schools.
This is particularly evident in the class schedule. In elementary, middle, and high school, students must follow the schedule set by the school. There is no right to refuse here.
… +50 lines (ctrl+r to expand)
I steeled myself. Just in case, I kept my guard up to the max. The possibility of a burglar was not zero, so I didn't forget to grip the key like a knuckle duster.
The basic rule is to ignore completely. If there is any danger to my life, I will retaliate without hesitation. While engraving that policy in my brain, I twisted the doorknob of my house.
● kakuyomu_mcp:get_episode_content (MCP)(work_id: "16817330651584484057", episode_id: "16817330651584506895")…
⎿ Sharpening my senses, I entered the entrance. At this moment, there were no signs of anyone. For now, it seems there won't be an encounter right from the start.
However, there were unfamiliar shoes, and they were women's, so it was almost certain that the intruder was the stalker in question.
… +72 lines (ctrl+r to expand)
"......Excuse me for intruding."
──As a result, the stalker left the room timidly about two hours later.
● Wonderful! I have finished reading the text of the 5 episodes. Now I will summarize and report the content I read.
● Update Todos
⎿ ☒ Retrieved the list of works from the top page of Kakuyomu
☒ Selected a suitable work
☒ Retrieved the episode list of the selected work
☒ Read the text of the first 5 episodes
☐ Summarize and report the content read
● Summary of the first 5 episodes of "It seems like an unknown girl is doing housework at home. But she was cute, so I'm keeping an eye on her."
Synopsis
This is a modern comedy work featuring Haruto Mizuki, a university student. He consults his friends about a stalker in his house, but since there is no actual harm and the stalker does housework, he calls them "the fairy Silky" and turns a blind eye to it.
Content of Each Episode
Episode 1: "Probably Silky"
- Reveals to friends during a scary story at an izakaya that there is a stalker in his house, but he turns a blind eye because they do housework.
- Friends are shocked and lecture him.
- The protagonist is grumpy and lazy but skilled, drawing illustrations and working part-time at a café.
Episode 2: "Confirming Silky"
- Sets up a hidden camera to confirm the identity of the stalker.
- It turns out to be a young woman, which brings relief.
- Witnesses her happily doing housework and changing her underwear to new ones.
- Decides to continue turning a blind eye since there is no actual harm.
Episode 3: "Who is Silky?"
- A scene of serving customers at the café "Marine Snow."
- Regular customers, a female band "Abandoned Garde," are celebrating their label contract.
- Thinks about the identity of the stalker but has no leads.
- Reveals a personality with few friends and difficulty remembering faces.
Episode 4: "Is Silky there?"
- Returns home early due to a canceled university lecture.
- Encounters the stalker during the time they are at home.
- Decides not to report to the police and to ignore thoroughly.
- Resolves to retaliate only if there is a threat to his life.
Episode 5: "I don't know Silky"
- Finally meets the stalker.
- Discovers a beautiful woman with brown hair hiding in the closet.
- Completely ignores her, and she leaves two hours later.
- Still remains an unknown identity, likely a case of one-sided infatuation.
Features
- The protagonist's super laid-back and overly rational thinking is amusing.
- A novel setting where stalker issues are accepted as "free housekeepers."
- A slice-of-life comedy with subtly thrilling developments.
- The protagonist's lack of human relationships and low sociality are at the core of the work.
It's quite a unique work! Despite being about a stalker, it has a peaceful tone, and the protagonist's values are so unique that it's very entertaining!
● Update Todos
⎿ ☒ Retrieved the list of works from the top page of Kakuyomu
☒ Selected a suitable work
☒ Retrieved the episode list of the selected work
☒ Read the text of the first 5 episodes
☒ Summarized and reported the content read
● All tasks are completed! I found an interesting work from Kakuyomu and successfully read and summarized the first 5 episodes. This work is a slice-of-life comedy, and the protagonist's values are so unique that it was extremely entertaining.
```
## Notes
- There is a possibility that it may stop working due to changes in Kakuyomu's HTML structure.
- To avoid excessive scraping, please set the `limit` parameter appropriately.
- In case of errors, user-friendly messages will be returned in Japanese.
