stewreads-mcp 0.1.1
Local MCP server that turns AI conversations into polished ebooks and delivers them to Kindle or email
Requires Python: >=3.10

# 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.

## Current Scope
- 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 (Claude Gmail connector preferred, SMTP fallback)
- Reuse current StewReads ebook-generation prompt

## Not In Scope (Current Iteration)
- PDF generation

## Requirements
- Python 3.10+
- uv

macOS install:
```bash
brew install uv
```

## Install (Recommended)
Install as a local tool:

```bash
uv tool install stewreads-mcp
```

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

## Install (Repo Development)
```bash
uv sync
```

## Configuration
Create `~/.config/stewreads/config.toml`:

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

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

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)

Fallback-only secret for built-in SMTP tool:
- `STEWREADS_GMAIL_APP_PASSWORD` (Gmail App Password)

## Run MCP Server (Tool Install)
```bash
stewreads-mcp
```

## Run MCP Server (Repo Development)
```bash
uv run stewreads-mcp
```

## Claude Desktop (Mac) Example
Add to Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "stewreads": {
      "command": "/Users/you/.local/bin/stewreads-mcp",
      "env": {
        "STEWREADS_CONFIG_PATH": "/Users/you/.config/stewreads/config.toml"
      }
    }
  }
}
```

If you want to use `email_ebook` (SMTP fallback tool), also set:

```json
"STEWREADS_GMAIL_APP_PASSWORD": "your-16-char-app-password"
```

## Exposed MCP Tools
- `get_stew_prompt()`
- `get_stew_config()`
- `get_email_status()`
- `save_stew_config(output_dir)`
- `save_ebook(markdown, title, filename?, original_prompt?)`
- `email_ebook(to_email?, ebook_path?, subject?, body?)` (SMTP fallback when connector is unavailable)

## 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. If Claude Gmail connector is available, ask Claude to send the saved EPUB using that connector.
5. If no connector is configured, call `get_email_status()` and then `email_ebook(...)`.

## 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.