io.github.slima-ai/slima
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Open source Repository Open in the app JSON README (API)
About
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- slima-ai
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.13
- Stars
- 1
- Last push
- 2026-04-24T17:08:41Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:24
- Updated
- 2026-08-29 04:01:24
- Origin id
io.github.slima-ai/slima
README
# Slima MCP
[](https://www.npmjs.com/package/slima-mcp)
[](https://opensource.org/licenses/MIT)
MCP (Model Context Protocol) Server for [Slima](https://slima.ai) - 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)
| Platform | Status | Notes |
|----------|--------|-------|
| Claude Desktop | ✅ | Native MCP support |
| ChatGPT Desktop | ✅ | Developer Mode (2025.10+) |
| Gemini CLI | ✅ | Native MCP support |
| Cursor | ✅ | Native MCP support |
| VS Code | ✅ | Via MCP extensions |
### Web Applications (Remote MCP - HTTP)
| Platform | Status | Notes |
|----------|--------|-------|
| Claude.ai | ✅ | OAuth login, no token needed |
| ChatGPT Web | ✅ | OAuth login, no token needed |
> 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](#recommended-claudeai--chatgpt-web-auto-updating) *(one-time setup, auto-updates forever)*
- Use **Claude Desktop / Cursor / Gemini CLI locally** → [Local install with `npx`](#local-claude-desktop--cursor--gemini-cli)
- Running in air-gapped / enterprise environments → [Self-host](#self-host-advanced)
### 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](https://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](https://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):
```json
{
"mcpServers": {
"slima": {
"command": "npx",
"args": ["-y", "slima-mcp@0"],
"env": {
"SLIMA_API_TOKEN": "slima_your_token_here"
}
}
}
}
```
Get your token from [Slima Settings](https://app.slima.ai/settings/api-tokens) or run `npx slima-mcp@0 auth` once to save it to disk.
#### Cursor
```json
{
"mcpServers": {
"slima": {
"command": "npx",
"args": ["-y", "slima-mcp@0"],
"env": {
"SLIMA_API_TOKEN": "slima_your_token_here"
}
}
}
}
```
#### Gemini CLI
```bash
gemini mcp add slima --command "npx -y slima-mcp@0"
```
> **Why `slima-mcp@0` instead of `slima-mcp` / `slima-mcp@latest`?** Using `@0` pins to the current major version — npx still 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.
#### Migrating from a global install
If you already installed globally with `npm install -g slima-mcp`:
```bash
# Remove the old global install (optional but cleaner)
npm uninstall -g slima-mcp
# Change your config `command` from "slima-mcp" to the npx form above, and restart the client.
```
Or, if you want to stay on a global install, remember to periodically run:
```bash
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 [Slima Settings](https://app.slima.ai/settings/api-tokens).
---
## 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:
| | 📖 Writing Studio (`book_type: "book"`) | 📝 Script Studio (`book_type: "script"`) |
|---|---|---|
| **Creation via MCP** | ✅ `create_book` works | ❌ use the Slima app UI |
| **Read** (any file) | ✅ | ✅ |
| **Write / Edit / Delete** | ✅ any path | ✅ only under `.script_studio/planning/**/*` |
| Structured files (`series.json`, `*.character`, `*.scene`, `*.storyline`, `*.note`, `*.location`, `season.json`, `episode.json`) | n/a | ❌ read-only via MCP — edits must go through the Script Studio UI |
| `analyze_chapter` (AI Beta Reader) | ✅ | ❌ not yet supported on structured scenes |
| `search_content` | all files | structured files excluded by default; pass `include_structured: true` to include them |
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
### Book Management
| Tool | Description |
|------|-------------|
| `create_book` | Create a new book in your library |
| `list_books` | List all books in your Slima library |
| `get_book` | Get details of a specific book |
| `get_book_structure` | Get the file/folder structure of a book |
| `get_writing_stats` | Get writing statistics for a book |
### File Operations
| Tool | Description |
|------|-------------|
| `read_file` | Read content of any file by path |
| `edit_file` | Edit specific text using search & replace |
| `write_file` | Replace entire content of a file |
| `create_file` | Create a new file in a book |
| `delete_file` | Delete a file from a book |
| `append_to_file` | Append content to end of a file |
| `search_content` | Search for text across all files |
### AI Beta Reader
| Tool | Description |
|------|-------------|
| `list_personas` | List available beta reader personas |
| `analyze_chapter` | Get AI beta reader feedback on a chapter |
## 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
```bash
slima-mcp auth # Authenticate with browser (recommended)
slima-mcp status # Check authentication status
slima-mcp logout # Remove saved credentials
slima-mcp --help # Show help
slima-mcp --version # Show version
```
Token is stored in `~/.slima/credentials.json` with secure permissions.
## Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SLIMA_API_TOKEN` | No* | - | Your Slima API token |
| `SLIMA_API_URL` | No | `https://api.slima.ai` | API endpoint (for development) |
| `DEBUG` | No | `false` | Enable debug logging |
*Not required if you used `slima-mcp auth`
## Development
### Local CLI Development
```bash
# Clone the repository
git clone https://github.com/slima-ai/slima-mcp.git
cd slima-mcp
# Install dependencies
npm install
# Build CLI
npm run build
# Run tests
npm test
# Run in development mode
npm run dev
```
### Cloudflare Worker Development
```bash
# Build the Worker
npm run build:worker
# Run Worker locally
npm run dev:worker
# Deploy to Cloudflare
npm run deploy:worker
# Deploy to preview environment
npm run deploy:worker:preview
```
### 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.
```bash
# 1. Bump version on dev branch
npm version patch # 0.1.10 → 0.1.11
# 2. Merge to main
git 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. Deploy after code changes:
```bash
npm run deploy:worker # Production (mcp.slima.ai)
npm run deploy:worker:preview # Staging
```
### MCP Registry (Manual)
To publish/update the server listing on the [MCP Registry](https://registry.modelcontextprotocol.io/):
```bash
mcp-publisher login github
mcp-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:
```bash
# Live logs from production Worker
wrangler 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](https://slima.ai)
- [Slima App](https://app.slima.ai)
- [MCP Documentation](https://modelcontextprotocol.io)
- [MCP Registry](https://registry.modelcontextprotocol.io/)
- [Report Issues](https://github.com/slima-ai/slima-mcp/issues)