Content
# webnovel-mcp (Free Version)
**A free, open-source MCP server for planning, writing, and managing webnovel projects with AI assistants.**
Supports **xianxia**, **LitRPG**, **progression fantasy**, **romance**, **fanfiction**, and all serial fiction formats. Works with any MCP-compatible client (Claude Desktop, Windsurf, Cursor, Cline, Roo, etc.).
---
## What Can This Do?
This MCP server helps you write webnovels by:
- **Organizing your novel** — Creates a project structure with folders for characters, chapters, and world-building
- **Tracking characters** — Stores character sheets with names, roles, appearances, and tracks how they change over time
- **Managing chapters** — Creates chapter outlines, saves written chapters, tracks word counts
- **Building your world** — Saves locations, factions, magic systems, cultures, and lore
- **Foreshadowing tracker** — Track planted seeds and planned payoffs across hundreds of chapters
- **Continuity checker** — Scans your project for overdue foreshadowing, stale characters, and chapter gaps
- **Timeline tracker** — Manage story chronology with events, dates, and time skips
- **LitRPG stat blocks** — Full RPG character tracking (level, stats, skills, inventory, equipment, quests)
- **Romance arc tracker** — Track relationship stages, romantic moments, and pacing for slow-burn arcs
- **Project export** — Generate comprehensive project summaries for backup and sharing
- **Writing prompts** — Guided prompts for chapter writing, character creation, arc planning, and brainstorming
---
## Quick Start Guide (For Non-Technical Users)
**Don't worry about the technical details — just tell your AI assistant:**
> "Please help me set up the webnovel-mcp server. I want to download it from https://github.com/netflypsb/webnovel-free-mcp, install it, and configure it for my MCP client."
Your AI assistant will handle all the setup for you.
---
## Step-by-Step Manual Installation
If you prefer to do it yourself or your AI needs guidance, follow these steps:
### Step 1: Download the Server
**Option A: Download as ZIP (Easiest)**
1. Go to: https://github.com/netflypsb/webnovel-free-mcp
2. Click the green **"Code"** button
3. Select **"Download ZIP"**
4. Extract the ZIP file to a folder on your computer (e.g., `C:\webnovel-mcp` on Windows or `~/webnovel-mcp` on Mac/Linux)
**Option B: Using Git (If you have Git installed)**
```bash
git clone https://github.com/netflypsb/webnovel-free-mcp.git
cd webnovel-free-mcp
```
### Step 2: Install Python (If Not Already Installed)
1. Go to https://python.org/downloads
2. Download Python 3.10 or newer
3. Run the installer
4. **Important on Windows:** Check the box that says "Add Python to PATH"
### Step 3: Install the Server
Open your terminal/command prompt in the downloaded folder and run:
**Windows:**
```powershell
pip install -e .
```
**Mac/Linux:**
```bash
pip3 install -e .
```
Or if you have `uv` installed (faster):
```bash
uv pip install -e .
```
### Step 4: Configure Your MCP Client
Add this to your MCP client configuration:
**For Claude Desktop:**
- Edit: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
```json
{
"mcpServers": {
"webnovel-mcp": {
"command": "python",
"args": ["-m", "webnovel_mcp.server"]
}
}
}
```
**For Windsurf:**
- Edit: `~/.codeium/windsurf/mcp_config.json` (Mac) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows)
```json
{
"mcpServers": {
"webnovel-mcp": {
"command": "python",
"args": ["-m", "webnovel_mcp.server"]
}
}
}
```
**For Cursor:**
- Go to Settings → MCP → Add Server
- Command: `python -m webnovel_mcp.server`
**For Cline/Roo (VS Code):**
- Edit: `.vscode/mcp.json` in your workspace
```json
{
"servers": {
"webnovel-mcp": {
"command": "python",
"args": ["-m", "webnovel_mcp.server"],
"env": {}
}
}
}
```
### Step 5: Restart Your AI Client
Close and reopen your AI assistant client to load the new tools.
---
## How to Use
Once set up, you can use natural language with your AI assistant:
**To create a new novel:**
> "Create a new xianxia webnovel called 'Path of the Immortal' with me as the author"
**To create characters:**
> "Create the protagonist Lin Wei, a 16-year-old cultivator from a poor village"
**To build the world:**
> "Create a world entry for the Azure Sky Sect, a major cultivation sect"
**To write chapters:**
> "Write Chapter 1 with a strong opening hook about Lin Wei discovering a mysterious artifact"
**To track foreshadowing:**
> "Track this foreshadowing: the jade pendant Lin Wei found will be revealed to be a sect founder's token in chapter 50"
**To check for continuity issues:**
> "Run a continuity check to see if I have any plot holes or forgotten foreshadowing"
Your AI will use the appropriate tools automatically!
---
## Available Tools (All Free)
| Tool | Description |
|------|-------------|
| `init_project` | Scaffold a complete webnovel project |
| `get_project_status` | View project stats and progress |
| `create_character` | Create a character sheet |
| `get_character` | Read a character sheet |
| `list_characters` | List all characters |
| `update_character` | Update character attributes |
| `create_chapter_outline` | Generate a chapter outline |
| `save_chapter` | Save a written chapter |
| `get_chapter` | Read a chapter |
| `list_chapters` | List all chapters |
| `create_world_entry` | Create a world-building entry |
| `get_world_entry` | Read a world-building entry |
| `list_world_entries` | List world-building entries |
| `get_style_guide` | Get the writing style guide |
| `track_foreshadowing` | Track planted seeds and planned payoffs |
| `get_foreshadowing_report` | View foreshadowing status report |
| `run_continuity_check` | Scan for continuity issues |
| `track_timeline` | Add timeline entries |
| `get_timeline` | View story timeline |
| `create_litrpg_stats` | Create LitRPG stat blocks |
| `update_litrpg_stats` | Update LitRPG stats |
| `create_romance_tracker` | Create romance arc tracker |
| `update_romance_tracker` | Update romance progression |
| `export_project_summary` | Export project summary |
---
## Project Structure
When you create a project, it looks like this:
```
your-novel/
├── novel.json # Project configuration
├── litconfig.json # Structural metadata
├── outline.md # Story outline
├── characters/ # Character sheets
├── chapters/ # Chapter files
├── worldbuilding/ # World-building entries
├── arcs/ # Arc outlines
└── metadata/ # Tracking files
```
---
## Resources
| URI | Description |
|-----|-------------|
| `template://novel-config` | novel.json template |
| `template://litconfig` | litconfig.json template |
| `template://character-sheet` | Character sheet template |
| `template://chapter-structure` | Chapter structure template |
| `template://world-state` | World state template |
| `template://style-guide` | Writing style guide |
---
## Prompts
| Prompt | Description |
|--------|-------------|
| `write-chapter` | Guided chapter writing with consistency checks |
| `create-character` | Guided character creation |
| `plan-arc` | Arc planning and structure |
| `brainstorm-story` | Story concept brainstorming |
---
## Troubleshooting
**"Python not found" error:**
- Make sure Python is installed and added to PATH
- Try using `python3` instead of `python` on Mac/Linux
**"Module not found" error:**
- Make sure you ran `pip install -e .` in the correct folder
- Try: `pip install mcp` and `pip install mcp[cli]`
**Tools not appearing in your AI client:**
- Restart your AI client completely
- Check the MCP configuration file for correct paths
- Look for error messages in the AI client's logs
**Permission errors on Mac/Linux:**
- You may need to use `sudo pip3 install -e .` (not recommended)
- Better: Use a virtual environment: `python3 -m venv .venv && source .venv/bin/activate && pip install -e .`
---
## License
MIT License. See [LICENSE](LICENSE) for details.
---
## Links
- **GitHub Repository:** https://github.com/netflypsb/webnovel-free-mcp
- **Model Context Protocol:** https://modelcontextprotocol.io
- **Original Repository (with marketplace version):** https://github.com/netflypsb/webnovel-mcp
---
## Getting Help
If you need help setting this up:
1. **Ask your AI assistant** — "Please help me set up the webnovel-mcp server from https://github.com/netflypsb/webnovel-free-mcp"
2. **Open an issue** on GitHub: https://github.com/netflypsb/webnovel-free-mcp/issues
3. **Check the original repository** for additional documentation: https://github.com/netflypsb/webnovel-mcp
---
**Happy Writing!**
