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

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.

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.

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.

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.
• 03 How slima-mcp versions work 0.3.0 (2026-09-09). The server never blocks an old client; an old client just has fewer tools. How to check your version and how to upgrade.

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 Arguments and behaviour for read_file / edit_file / write_file / create_file / delete_file / append_to_file / search_content, and the file types this group cannot touch.
• 03 AI Reader tools (2) Two MCP tools expose AI Beta Readers: list_personas, analyze_chapter. Inputs, outputs, mapping to in-Slima reading.
• 04 Structured editing tools (update_*) How the update_* tools change a beat board, timeline, screenplay, relationship map or world map: one operation at a time, op_ref chaining, all-or-nothing.
• 05 Notes and comments tools Let an outside AI read and write notes and join the comment loop: list_notes / create_note / list_comments / create_comment / resolve_comment / reopen_comment.
• 06 Semantic search vs full-text search semantic_search matches meaning, search_content matches words. Which question belongs to which tool, and how the index is built.

File types & permissions

• 01 What MCP can do, file type by file type The full matrix: prose files take whole-file writes, five structured types take field-level tools, some types take neither — plus the path rules for older Script Studio books.
• 02 Structured-file protections: how to read a refusal What AI_READONLY_FILE_TYPE, SUBSCRIPTION_REQUIRED, INVALID_PATH and FOLDER_NOT_EMPTY each mean, and the right next step for each.
• 03 Tools that behave differently on some files The exceptions in read_file, search_content, semantic_search, analyze_chapter, get_writing_stats, create_file and delete_file — and what to do about each.

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.
• 03 Guides and writing skills get_capabilities, Slima's own operating guides and its writing skills: how Slima hands its own rules to your AI tool.
• 04 Let an AI see a relationship map view_relationship_map returns a picture plus a readable summary, which beats reading raw .map JSON — and the four replies you will meet.

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 What AI_READONLY_FILE_TYPE, SUBSCRIPTION_REQUIRED, INVALID_PATH and FOLDER_NOT_EMPTY each mean, plus the create_file case that succeeds and leaves an empty file.
• 04 Advanced: debug the OAuth flow The 9-step OAuth flow: DCR → authorize → callback → token → mcp. Trace which step fails with `wrangler tail` / curl.