Slima MCP

Read & write your Slima books from Claude / ChatGPT / Cursor / Gemini

First-time MCP setup

• 01 What Slima MCP is MCP (Model Context Protocol) is the standard for AI tools to read & write external systems. Slima MCP lets Claude / ChatGPT / Cursor / Gemini read & write your Slima books directly.
• 02 Slima MCP vs file MCP vs built-in Coach Three routes — Slima MCP (API into books), file MCP (point at a local folder), in-editor AI Coach.
• 03 Pick your connection method: Web vs local Two routes: Web (OAuth, used by claude.ai / ChatGPT) vs local stdio (npm package, used by Claude Desktop / Cursor / Gemini CLI).

</ul>

Web connection (OAuth)

• 01 Connect from Claude.ai (recommended) Add Slima MCP as a Custom Connector in Claude.ai. OAuth flow, required Claude tier (Pro / Max / Team / Enterprise).
• 02 Connect from ChatGPT ChatGPT requires Developer Mode (2025.10+) + Custom MCP Server + OAuth. Plus / Pro tier only.

</ul>

Local connection (stdio)

• 01 Connect Claude Desktop Claude Desktop local: edit claude_desktop_config.json + npx slima-mcp@0 + token env var. Mac / Win paths.
• 02 Connect Cursor Cursor → Settings → MCP → add server + npx slima-mcp@0. Similar to Claude Desktop with a different UI.
• 03 Connect Gemini CLI Gemini CLI: `gemini mcp add slima --command "npx -y slima-mcp@0"`. Requires Gemini CLI ≥ 0.4.
• 04 Connect VS Code VS Code connects via MCP extensions. Common ones: MCP Tools / Continue.

</ul>

API tokens

• 01 Get SLIMA_API_TOKEN Two paths: run `npx slima-mcp@0 auth` (browser sign-in, stores at ~/.slima/credentials.json); or set SLIMA_API_TOKEN manually on a headless / CI box.
• 02 slima-mcp CLI commands reference Every `slima-mcp` CLI command: auth / status / logout / --help / --version. Description + examples.
• 03 Manage authorized apps Account → API tokens / Authorized apps: see what's connected, last-used time, revoke individually or in bulk.

</ul>

Versions & upgrades

• 01 Why `slima-mcp@0`: version-pinning explained All examples use `slima-mcp@0`, not `slima-mcp`. `@0` is a major-version pin — auto-takes 0.x patches / minors but you opt into 1.0 breaking changes.
• 02 Migrate from global install to `npx` Older versions used `npm install -g slima-mcp`. The new pattern is `npx -y slima-mcp@0`. Why migrate and how.

</ul>

Tools reference

• 01 Book management tools (5) Slima MCP exposes 5 book-level tools: create_book / list_books / get_book / get_book_structure / get_writing_stats. Inputs, outputs, examples.
• 02 File operation tools (7) Seven file-level tools: read_file / edit_file / write_file / create_file / delete_file / append_to_file / search_content. Permission rules + examples.
• 03 AI Reader tools (2) Two MCP tools expose AI Beta Readers: list_personas, analyze_chapter. Inputs, outputs, mapping to in-Slima reading.

</ul>

Writing vs Script Studio

• 01 MCP behavior by studio: full matrix Writing Studio vs Script Studio under MCP — which paths are writable, which are read-only, special structured-file handling.
• 02 Script Studio structured file protections All structured files in Script Studio (scenes / characters / storylines / seasons / episodes) are read-only over MCP. Only `.script_studio/planning/**/*` is writable. Why + how (not) to work around.
• 03 Script Studio tool-specific limits `search_content` excludes structured files by default; `analyze_chapter` doesn't support scene files. How to work around or supplement.

</ul>

Advanced: schema & self-host

• 01 Query book schema with the resource MCP resource `slima://books/{book_token}/schema` returns precise read-only / writable path rules — AI uses this to know if a path is writable.
• 02 Self-host Cloudflare Worker (advanced) Slima MCP server runs on Cloudflare Workers (open-source). You can fork, deploy your own, customize OAuth / add middleware.

</ul>

Troubleshooting

• 01 Can't connect: 401 / Authorization header Most common MCP connect failure: 401 Unauthorized. Causes: token expired / config wrong / WWW-Authenticate flow failed. Diagnostics.
• 02 Token expired or needs reauth MCP tokens are issued by the Slima OAuth sign-in and expire periodically. Expiry returns 401; re-auth (often automatic on the web) fixes it. How to detect / refresh.
• 03 Permission denied on write Write fails 400 INVALID_PATH usually means Script Studio structured files — edit in the Slima UI or write to `.script_studio/planning/`.
• 04 Advanced: debug the OAuth flow The 9-step OAuth flow: DCR → authorize → callback → token → mcp. Trace which step fails with `wrangler tail` / curl.

</ul>