stewreads

StewReads is a local MCP server that transforms AI conversations into clean, well-formatted ebooks. Everything runs on your machine, with no account and no cloud backend required. Generate EPUB files from your chats and send them directly to Kindle or any email address. Works with Claude Desktop and other MCP-compatible clients.

Website vs Local Package

The official StewReads website is stewreads.com. This PyPI package, stewreads-mcp, is the local-first MCP version for people who want to run ebook generation from Claude Desktop on their own machine. Installing this package does not connect to a StewReads cloud backend.

Features

• Local-first MCP server with no login or cloud backend
• Local stdio MCP server (no backend calls)
• EPUB generation from markdown
• Save generated ebooks to a configured local directory
• Send generated EPUB files by email via built-in Gmail SMTP (App Password)
• Optional MP3 audiobook generation via ElevenLabs TTS

Use Cases

• Learn a new topic with Claude and turn the discussion into a polished ebook for later reading.
• Generate a focused ebook before a flight and read offline on your e-reader.
• Turn long planning or research chats into one clean document you can revisit anytime.
• Create Kindle-ready study notes from tutoring or interview-prep conversations.
• Save and share AI-generated explainers with friends or teammates over email.

Requirements

• Python 3.10+
• uv for repo development

Install From PyPI

Install the released package:

pip install stewreads-mcp

macOS install:

brew install uv

Setup From Repo

Clone and install from this repository:

git clone git@github.com:ankitvg/stewreads-local.git
cd stewreads-local
uv sync

This includes pandoc via pypandoc-binary, so no separate pandoc install is required.

Update Dependencies

uv sync

Configuration

Create ~/.config/stewreads/config.toml:

[paths]
output_dir = "/Users/you/Projects/generated_books"

[email]
from_email = "you@gmail.com"
default_to_email = "kindle-or-reader@example.com"

Important (Kindle Users): For Kindle delivery to work, you MUST add your from_email to your Approved Personal Document E-mail List in your Amazon account settings. Otherwise, Amazon will block the incoming ebook for security.

Optional environment overrides:

• STEWREADS_CONFIG_PATH (path to config file)
• STEWREADS_OUTPUT_DIR (overrides configured output dir)
• STEWREADS_FROM_EMAIL (overrides sender email)
• STEWREADS_DEFAULT_TO_EMAIL (overrides default recipient email)

Required secret for email sending:

• STEWREADS_GMAIL_APP_PASSWORD (Gmail App Password)

Audiobook environment variables (used only when save_ebook(..., create_audio=true)):

• ELEVENLABS_API_KEY (required to generate MP3 files)
• ELEVENLABS_VOICE_ID (optional voice override)

Audiobook defaults:

• Voice: Rachel (21m00Tcm4TlvDq8ikWAM)
• Model: eleven_multilingual_v2
• Output format: mp3_44100_128

Run MCP Server

uv run stewreads-mcp

Claude Desktop (Mac) Example

Add to Claude Desktop's claude_desktop_config.json MCP config:

{
  "mcpServers": {
    "stewreads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/you/Projects/stewreads-local",
        "run",
        "stewreads-mcp"
      ],
      "env": {
        "STEWREADS_CONFIG_PATH": "/Users/you/.config/stewreads/config.toml",
        "STEWREADS_GMAIL_APP_PASSWORD": "your-16-char-app-password",
        "ELEVENLABS_API_KEY": "your-elevenlabs-api-key",
        "ELEVENLABS_VOICE_ID": "21m00Tcm4TlvDq8ikWAM"
      }
    }
  }
}

Exposed MCP Tools

• get_stew_prompt()
• get_stew_config()
• get_email_status()
• save_stew_config(output_dir)
• save_ebook(markdown, title, filename?, original_prompt?, create_audio?)
• email_ebook(to_email?, ebook_path?, subject?, body?)

Async Audiobook Behavior

When you call save_ebook(..., create_audio=true):

• EPUB save completes first and Claude can return that result immediately.
• MP3 generation continues in the background and may still be running after the response.
• The response includes audio_status="generating" and an audio_path you can check in your output directory.

First-Time Claude Flow

1. Call get_stew_config().
2. If configured is false, ask the user for their preferred output directory and call save_stew_config(output_dir=...).
3. Call save_ebook(...) after config is set.
4. Call get_email_status() before sending.
5. Call email_ebook(...) to send the latest EPUB (or specify ebook_path).

Testing (Local Development)

Run tests:

uv run --with pytest python -m pytest -q tests

Optional lint check:

uv run --with ruff ruff check src tests

Dev Shell Safety

When running multi-step shell commands, you may see set -euo pipefail:

• -e: stop on command failure.
• -u: fail on unset variables.
• -o pipefail: fail if any command in a pipeline fails.