SillyTavern MCP Server

A read-only Model Context Protocol server that exposes a SillyTavern user directory (characters, personas, chat-completion presets, lorebooks, chats) to general-purpose agent clients — Claude Desktop, Raycast, BoltAI, etc.

See docs/MVP.md for the full design spec: architecture, handle scheme, envelope format, and tool inventory.

Status

The full MVP tool inventory (§6) is implemented and end-to-end tested over real stdio:

• Characters — list-characters, get-character

• Personas — list-personas, get-persona

• Presets — list-presets, get-preset, export-preset

• Lorebooks — list-lorebooks, get-lorebook, search-lorebook

• Chats (the ladder) — list-chats → get-chat-manifest → get-chat-summaries → search-chat → get-messages → export-chat

Remaining work is the explicitly-deferred post-MVP backlog (docs/MVP.md §8) — track it via bd (this repo's issue tracker — run bd ready / bd list).

Related MCP server: MCP Server Template (Python)

Project layout

packages/core/          pure library — no MCP awareness
  fs/                   the ONLY module that touches the filesystem (reads + export writes)
  resolve/               user-dir resolution, startup validation, handles, name resolution
  parse/                 one parser per surface (cards, chats, lorebooks, presets, personas, summaries)
  render/                 transcript assembly, preset outline/full, token estimates, prefix stripping
packages/mcp/            stdio MCP adapter — envelope, tool registration, one file per tool group
packages/cli/            st-mcp CLI — npx entrypoint + `doctor` subcommand
docs/MVP.md              design spec

Getting started locally

npm install
npm run build
node packages/cli/dist/bin.js --user-dir /path/to/SillyTavern/data/default-user

--user-dir is optional — see docs/MVP.md §3 for the full resolution order (flag > SILLYTAVERN_USER_DIR env var > ~/.config/st-mcp/config.json > platform-default guesses). The server refuses to start and lists every path it tried if none resolve to a valid SillyTavern user directory.

To check your user-dir without starting the server:

node packages/cli/dist/bin.js doctor --user-dir /path/to/SillyTavern/data/default-user

Running tests

npm test

Learn more

• MCP specification

• TypeScript SDK documentation