Slima MCP

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` for auto browser sign-in storing at ~/.slima/credentials.json; or manually from Account → API tokens.

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

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.

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.

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.

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

  Tokens have TTLs — OAuth 30 days, personal tokens 90 days. Expiry returns 401 + reauth_url. 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.