StoryForge: Installation
Install and set up StoryForge: requirements, plugin installation, the setup skill, your first author profile and Windows notes.
StoryForge: Installation
Requirements
| Component | Purpose |
|---|---|
| Claude Code | Plugin host |
| Python 3.10 or newer | Runtime of the MCP server (runs in its own virtual environment) |
| Pandoc | EPUB and PDF export |
| xelatex | PDF export (the export command calls Pandoc with --pdf-engine=xelatex) |
Calibre (ebook-convert) |
MOBI export only, optional |
You do not need your own API key. The plugin works through the Claude access of Claude Code.
Install the plugin
The project README names this route:
claude plugin add storyforge
The repository ships a plugin manifest (.claude-plugin/plugin.json) and a marketplace file (.claude-plugin/marketplace.json) for this. The manifest wires in the skills from skills/, the MCP server storyforge-mcp and three hooks.
Run the setup
After installation, the setup skill creates everything else:
/storyforge:setup
The skill works through these steps (the numbers match those in the skill):
- Detect the platform and find a working Python interpreter (
python3, thenpython, thenpy -3, plus known install locations on Windows). - Check that Python 3.10 or newer is available.
- Create the virtual environment at
~/.storyforge/venvif it is missing. - Install the dependencies from the plugin's
requirements.txt:mcp(version 2.x),pyyaml,pymupdf,python-docx, plus a few minimum versions for security-relevant transitive packages. - Create the directories
~/.storyforge/cacheand~/.storyforge/authors. - Copy
config/config.example.yamlto~/.storyforge/config.yamlif that file does not exist yet. - Check Pandoc (
pandoc --version) and print an install hint if it is missing. - Check Calibre (
ebook-convert --version, only needed for MOBI). - Test the MCP import with the virtual environment's Python.
- Create
~/projekte/book-projects/projectsif it is missing. - Report the status and suggest the next step.
Step 9 always creates
~/projekte/book-projects/projects, even if you set a differentpaths.content_rootin the config. Adjust the path afterwards in the configuration.
The setup skill doubles as the repair tool: if the MCP server does not respond, run it again.
How the MCP server is started
The plugin's .mcp.json starts the server storyforge-mcp through a small wrapper that calls the virtual environment's Python.
| Platform | Wrapper | Interpreter |
|---|---|---|
| Linux, macOS | bin/run-server |
~/.storyforge/venv/bin/python3 |
| Windows | bin/run-server.cmd |
%USERPROFILE%\.storyforge\venv\Scripts\python.exe |
The three hooks also run through this wrapper. Without the virtual environment at ~/.storyforge/venv, neither the server nor the hooks run.
Windows: python3 is not found
On Windows, python3 and python sometimes exit with code 49 and no output even though Python is installed. That is the Microsoft Store placeholder, not a missing installation. The setup skill therefore also tries py -3 and the usual install directories. If it still reports that Python is missing, install Python 3.10 or newer from python.org and enable "Add python.exe to PATH".
First steps after installation
/storyforge:create-author My Name
/storyforge:new-book
/storyforge:help
/storyforge:create-authorcreates the author profile that drives every prose decision./storyforge:new-bookcreates the book project with its directory scaffold./storyforge:helpshows all skills and the workflow.
Continue with the configuration and the skills reference.