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