Slima

Slima MCP

[npm version] [License: MIT]

MCP (Model Context Protocol) Server for Slima - AI Writing IDE for Novel Authors.

Connect your Slima books to any MCP-compatible AI tool - one server, all platforms.

Supported Platforms

Desktop Applications (Local MCP - stdio)

Web Applications (Remote MCP - HTTP)

MCP became the industry standard in December 2025 when Anthropic, OpenAI, and Block co-founded the Agentic AI Foundation under the Linux Foundation.

Features

Book Management

• Create new books
• List and view your books
• Get file/folder structure
• Track writing statistics

File Operations

• Read any file by path
• Edit specific text (search & replace)
• Write (replace) file content
• Create new files
• Delete files
• Append content to files
• Search across all files

AI Beta Reader

• Get feedback from virtual reader personas
• Analyze chapters with different reader perspectives

Quick Start

Pick the path that matches how you use AI:

• ⭐ Use claude.ai / ChatGPT in a web browser → Recommended: web connector (one-time setup, auto-updates forever)
• Use Claude Desktop / Cursor / Gemini CLI locally → Local install with npx
• Running in air-gapped / enterprise environments → Self-host

Recommended: claude.ai / ChatGPT Web (auto-updating)

If you chat with Claude or ChatGPT in a browser, this is the easiest and most future-proof option. Configure once and you will automatically get every Slima MCP update — no upgrade commands, no config edits.

MCP URL: https://mcp.slima.ai/mcp

claude.ai (Pro / Max / Team / Enterprise)

1. Sign in at claude.ai.
2. Open Settings → Connectors (or Integrations depending on your plan).
3. Click Add custom connector.
4. Fill in:
   • Name: Slima
   • URL: https://mcp.slima.ai/mcp
5. Click Connect → you will be redirected to slima.ai to approve → return to claude.ai.
6. The Slima tools icon appears in your chat input. You're done.

ChatGPT (Plus / Pro, Developer Mode)

1. Sign in at chatgpt.com.
2. Open Settings → Connectors → Advanced and toggle Developer Mode on (2025.10+).
3. Back in Connectors, click Create → Custom MCP Server.
4. Fill in:
   • Name: Slima
   • Server URL: https://mcp.slima.ai/mcp
   • Authentication: OAuth
5. Click Create → approve the OAuth flow.

After setup, Slima features roll out automatically on your next conversation. No restarts, no reinstalls.

Local: Claude Desktop / Cursor / Gemini CLI

Use this if you want offline-friendly operation, faster startup, or you need to run MCP alongside other stdio servers.

Recommended config — pinned to the major version so you pick up new features automatically but never break on a 1.0 release:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{  "mcpServers": {    "slima": {      "command": "npx",      "args": ["-y", "slima-mcp@0"],      "env": {        "SLIMA_API_TOKEN": "slima_your_token_here"      }    }  }}

Get your token from Account settings → Authorized Apps or run npx slima-mcp@0 auth once to save it to disk.

Cursor

{  "mcpServers": {    "slima": {      "command": "npx",      "args": ["-y", "slima-mcp@0"],      "env": {        "SLIMA_API_TOKEN": "slima_your_token_here"      }    }  }}

Gemini CLI

gemini mcp add slima --command "npx -y slima-mcp@0"

Or install it as a Gemini CLI extension (it asks for your API token once and keeps it in the system keychain):

gemini extensions install https://github.com/slima-ai/slima-mcp

Why slima-mcp@0 instead of slima-mcp / slima-mcp@latest? Using @0 pins to the current major version — npx fetches new 0.x.y releases automatically (so you get features + bug fixes), but when we ship 1.0.0 with breaking changes you won't silently pick it up without updating your config. We'll announce the @1 switch in the release notes.

⚠️ This only holds if you do not also have a global slima-mcp install. npx pkg@<range> will happily satisfy the range from a package already on your PATH and never contact the registry at all. Measured on 2026-09-09 with a global 0.2.0 present and 0.3.0 on npm:

command	resolved
npx -y slima-mcp@0	0.2.0 — used the global install
npx -y slima-mcp	0.2.0 — same
npx -y slima-mcp@latest	0.3.0 — a dist-tag forces a registry lookup
npx -y [email protected]	0.3.0 — the global can't satisfy an exact newer version

So a stale global install makes the npx form silently stop upgrading, while the server keeps telling you to upgrade. Remove it — see below.

Migrating from a global install

If you already installed globally with npm install -g slima-mcp:

# Remove the old global install — REQUIRED, not just tidiness.# Leaving it in place makes `npx -y slima-mcp@0` resolve to the old global copy# forever (see the warning above), so you'd stay outdated while being told to upgrade.npm uninstall -g slima-mcp
# Then change your config `command` from "slima-mcp" to the npx form above, and restart the client.# Verify: `npx -y slima-mcp@0 --version` must print the version shown by `npm view slima-mcp version`.

⚠️ Check every place you may have installed it. A global install can exist per Node version manager environment and per OS — on WSL setups it is common to have one under nvm and one under Windows' AppData/Roaming/npm, at two different versions, with only one of them on the PATH your MCP client actually uses.

Or, if you want to stay on a global install, remember to periodically run:

npm install -g slima-mcp@latest

Otherwise your local client will drift from the MCP tools/schema the Slima backend exposes.

Self-host (advanced)

You can also clone this repo and deploy the Cloudflare Worker yourself. See wrangler.toml + npm run deploy:worker. Not required for normal use.

Remote MCP Security

The hosted Remote MCP Server at https://mcp.slima.ai/mcp uses:

• OAuth 2.0 + PKCE for authentication — no tokens copy-pasted.
• No secrets stored server-side — credentials never leave Slima's auth server.
• Session-based: OAuth tokens are stored in Cloudflare KV, scoped per session.
• Revocable anytime from Account settings → Authorized Apps: revoking an app takes effect on its next request.

Book Types: Writing Studio vs Script Studio

Slima books come in two flavors, distinguished by the book_type field. MCP behaves slightly differently for each:

For per-book details, ask your AI client to read the resource slima://books/{book_token}/schema — it returns a JSON spec of exactly which paths are writable/read-only for that specific book.

list_books tags every book with its studio icon (📝 / 📖) so you (and the AI) can tell them apart at a glance.

Available Tools

39 tools. R = read-only (never changes your book); W = changes something and says so in its description. Reads and writes are always separate tools.

Start here (teaching)

Book Management

File Operations

Every write is a commit in the book's version history, so it can be reviewed and reverted.

Structured Files (one field at a time)

Notes and Comments

AI Beta Reader

Teams

Usage Examples

Once configured, you can ask your AI:

Book & Content:

• "Create a new book called 'My Novel'"
• "List my books in Slima"
• "Show me the structure of my novel"
• "Read chapter 3 of my book"
• "What are my writing stats?"

File Operations:

• "Read the character profile for my protagonist"
• "Edit chapter 1 and change 'John' to 'James'"
• "Create a new file called worldbuilding.md with notes about the magic system"
• "Search for all mentions of 'blue eyes' in my book"
• "Append this new paragraph to chapter 5"

AI Feedback:

• "Get feedback on chapter 5 from a young reader perspective"
• "Analyze my opening scene from a critic's perspective"

CLI Commands

slima-mcp auth      # Authenticate with browser (recommended)slima-mcp status    # Check authentication statusslima-mcp logout    # Remove saved credentialsslima-mcp --help    # Show helpslima-mcp --version # Show version

Token is stored in ~/.slima/credentials.json with secure permissions.

Environment Variables

*Not required if you used slima-mcp auth

Development

Local CLI Development

# Clone the repositorygit clone https://github.com/slima-ai/slima-mcp.gitcd slima-mcp
# Install dependenciesnpm install
# Build CLInpm run build
# Run testsnpm test
# Run in development modenpm run dev

Cloudflare Worker Development

# Build the Workernpm run build:worker
# Run Worker locallynpm run dev:worker
# Deploy to Cloudflarenpm run deploy:worker
# Deploy to the test environment (test-mcp.slima.ai)npm run deploy:worker:test

Project Structure

slima-mcp/├── src/│   ├── core/           # Shared core modules│   │   ├── api/        # Slima API Client│   │   ├── tools/      # MCP Tool implementations│   │   └── utils/      # Utilities and errors│   ├── cli/            # CLI entry point (stdio transport)│   │   ├── index.ts    # CLI main│   │   ├── auth.ts     # Authentication commands│   │   └── server.ts   # MCP Server for CLI│   └── worker/         # Cloudflare Worker (HTTP transport)│       ├── index.ts    # Worker entry point│       └── oauth.ts    # OAuth 2.0 + PKCE client├── wrangler.toml       # Cloudflare Worker config├── tsup.config.ts      # CLI build config└── tsup.worker.config.ts # Worker build config

Security

• API tokens are stored locally and never shared
• All communication with Slima API uses HTTPS
• Tokens can be revoked anytime from Slima settings

Release & Deployment

npm (Automatic)

Merge to main with a version bump in package.json triggers automatic npm publish via GitHub Actions.

# 1. Bump version on dev branchnpm version patch   # 0.1.10 → 0.1.11
# 2. Merge to maingit checkout main && git merge dev && git push
# 3. CI runs tests → publish.yml publishes to npm + creates git tag

Cloudflare Worker (Manual)

Worker deployment is separate from npm, and nothing triggers it automatically. Publishing to npm does NOT update mcp.slima.ai. Remote clients (claude.ai / ChatGPT connectors) talk to the Worker, so they keep running the old tool set until someone runs this by hand:

npm run deploy:worker:test   # Test  (test-mcp.slima.ai -> test-api.slima.ai)npm run deploy:worker        # Prod  (mcp.slima.ai      -> api.slima.ai)

Deploy test first and check curl https://test-mcp.slima.ai/ | jq .version before doing prod; the same one-liner against mcp.slima.ai is how you tell whether the Worker is behind npm at all.

2026-09-09: the Worker sat on 0.2.0 for four and a half months — it was last deployed the same day npm 0.2.0 shipped, so every change after that reached npm users and no connector users. There is no alarm for this; the version endpoint is the only signal.

There used to be a deploy:worker:preview script pointing at an [env.preview] block. It was removed on 2026-09-09: its KV id was the literal placeholder string, staging-api.slima.ai does not resolve, and — worst — it defined no routes. routes is an inheritable key in wrangler, so that command would have inherited the top-level mcp.slima.ai custom domain and pointed production's hostname at the preview Worker. The real staging environment is [env.test].

MCP Registry (Manual)

To publish/update the server listing on the MCP Registry:

mcp-publisher login githubmcp-publisher publish

Requires mcpName in package.json and server.json in repo root.

Operational Notes

Debugging Worker OAuth

When troubleshooting claude.ai or ChatGPT connector issues:

# Live logs from production Workerwrangler tail slima-mcp

All OAuth endpoints log key parameters (client_id, redirect_uri, token prefix, etc.) to help trace the flow.

Worker OAuth Flow (claude.ai / ChatGPT)

Client POST /mcp → 401 + WWW-Authenticate header  → Client GET /.well-known/oauth-protected-resource  → Client GET /.well-known/oauth-authorization-server  → Client POST /register (DCR)  → Client redirects user to GET /authorize    → Worker redirects to Rails OAuth    → User authorizes → Rails redirects to Worker /callback    → Worker issues auth code → redirects to client callback  → Client POST /token (exchange code for access_token)  → Client POST /mcp (Authorization: Bearer {access_token})

Known Constraints

• Worker Bearer token validation accepts all non-empty tokens (not just slima_ prefix) to support OAuth-issued tokens. Rails API performs actual validation.
• getTokenFromSession() checks Authorization header first, then falls back to cookie session.
• MCP Inspector (npx @modelcontextprotocol/inspector) is useful for testing the full OAuth flow independently.

License

MIT

Links

• Slima Website
• Slima App
• MCP Documentation
• MCP Registry
• Report Issues