sillytavern-mcp

English

An MCP server that bridges AI coding agents with SillyTavern. It lets AI assistants create character cards, run server diagnostics, and read console logs — directly from their chat interface.

Compatible with any MCP client: Claude Code, Cursor, Kilo, VS Code (via MCP extensions), and more.

No SillyTavern modifications needed. No plugins required for basic operation. Just configure and go.

Built with fastmcp + uv.

Tools

| Tool | What it does | |------|-------------| | write_character_card | Create a character card from text attributes (name, personality, first message...). Writes a V2/V3 PNG card to the characters directory. | | import_character_card | Import an existing character card PNG file. Copies as-is without modifying metadata. | | get_st_diagnostics | Comprehensive health check on a running SillyTavern instance — API connectivity, character card integrity, chat files, config, plugins. Zero configuration needed. | | get_st_console | Read the SillyTavern console log captured by the st-console-logger plugin. Supports incremental reading. | | setup_st_logging | One-click install of the console logger plugin into SillyTavern's plugins/ directory and enable server plugins in config.yaml. | | list_doc | List all available documentation topics (TH, EJS Templates, MVU). | | read_doc | Read the full content of a documentation page by topic name. | | convert_png_to_json | Extract V2/V3 character metadata from a PNG card and save as .json. | | convert_json_to_png | Build a PNG character card from a .json file with avatar resolution (embedded > file > ST default > placeholder). | | embed_cover_image | Embed a cover/banner image into a character card's extensions.cover as base64 data URI. | | extract_cover_image | Extract the cover image from a character card and save as an image file. | | get_character_card_info | Read a character card PNG and return its metadata as a formatted text summary. | | explode_character_card | Split a large JSON character card into multiple smaller YAML/MD/JS/HTML files organized by module. | | implode_character_card | Reassemble an exploded character card directory back into a single JSON file. |

Bundled Resources

This server bundles 57 distilled documentation pages across four SillyTavern frameworks:

| Framework | Topics | Coverage | |-----------|--------|----------| | SillyTavern REST API | 11 | Characters, chats, world info, groups, AI backends, tokenizers, settings, users, extensions, media, TTS/STT/search/SD | | JS-Slash-Runner (Tavern Helper) | 21 | Scripting, macros, events, characters, worldbooks, variables, regex, audio, presets, chat messages, injection, extensions | | ST-Prompt-Template (EJS Templates) | 14 | EJS template engine, variable system, injection, characters, presets, regex, utilities, events, worldbook | | MagVarUpdate (MVU Variable Framework) | 11 | Variable state management, schema protection, commands, extra-model analysis, cleanup, init, API |

Available via list_doc and read_doc tools. The AI can reference these docs to help write or debug scripts without leaving the chat.

Architecture

MCP Client (Claude Code / Cursor / Kilo / ...)
    │
    ▼
sillytavern-mcp (this project) ←── reads/writes ──→ ST data directory (character cards, logs)
    │
    └── talks to ──→ SillyTavern HTTP API (status, character list, CSRF)

Setup

Prerequisites: Python 3.11+ and uv.

git clone <repo-url> sillytavern-mcp
cd sillytavern-mcp
uv sync

MCP Client Configuration

Add the server to your MCP client's configuration.

Option 1: VS Code

In .vscode/mcp.json or your VS Code MCP settings:

{
  "servers": {
    "sillytavern-mcp": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
      "env": {
        "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
        "SILLYTAVERN_USER": "default-user",
        "SILLYTAVERN_URL": "http://localhost:8000"
      }
    }
  }
}

Option 2: Claude Code

In ~/.claude/settings.json:

{
  "mcpServers": {
    "sillytavern-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
      "env": {
        "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
        "SILLYTAVERN_USER": "default-user",
        "SILLYTAVERN_URL": "http://localhost:8000"
      }
    }
  }
}

Option 3: Cursor

In Cursor settings → MCP Servers → Add new:

{
  "name": "sillytavern-mcp",
  "type": "command",
  "command": "uv",
  "args": ["run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
  "env": {
    "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
    "SILLYTAVERN_USER": "default-user",
    "SILLYTAVERN_URL": "http://localhost:8000"
  }
}

Option 4: Kilo

In ~/.config/kilo/kilo.json:

{
  "sillytavern-mcp": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
    "environment": {
      "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
      "SILLYTAVERN_USER": "default-user",
      "SILLYTAVERN_URL": "http://localhost:8000"
    },
    "enabled": true
  }
}

Quick Test

After configuration, verify the server connects correctly:

uv run python -m sillytavern_mcp

It will start in stdio mode and wait for MCP protocol messages from your client. No output means it's working.

Ask your AI assistant: "Can you check the status of my SillyTavern?"

Enable Console Logging (Optional)

To let your AI assistant read SillyTavern's console output (errors, model loading, etc.):

Ask your assistant to run setup_st_logging. It will automatically:

Copy the logger plugin to ST's plugins/ directory
Enable server plugins in config.yaml (enableServerPlugins: true)

Then restart SillyTavern. After restart, console output is captured to data/st_console.log — readable via the get_st_console tool.

No terminal commands needed — your assistant handles everything.

Configuration Reference

| Environment Variable | Default | Description | |----------|---------|-------------| | SILLYTAVERN_DATA_DIR | Auto-detect | Path to SillyTavern data/ directory | | SILLYTAVERN_USER | default-user | SillyTavern user handle | | SILLYTAVERN_URL | http://localhost:8000 | SillyTavern HTTP API base URL |

Project Structure

sillytavern-mcp/
├── sillytavern_mcp/
│   ├── __init__.py              # FastMCP instance
│   ├── __main__.py              # Entry point (python -m)
│   ├── server.py                # Tool & resource registration
│   ├── png_util.py              # PNG chunk read/write (character card format)
│   ├── character_schema.py      # V2/V3 character card JSON builder
│   ├── default_avatar.py        # Fallback avatar generator
│   ├── st_client.py             # SillyTavern HTTP API client
│   ├── utils.py                 # Shared helpers, path resolution
│   ├── st_console_plugin/       # Node.js server plugin for log capture
│   │   ├── index.js
│   │   └── package.json
│   ├── resources/
│   │   ├── __init__.py
│   │   └── docs_distilled.py    # 57 doc resources (docs://STAPI/*, docs://TH/*, docs://STPT/*, docs://MVU/*)
│   └── tools/
│       ├── write_character.py
│       ├── import_character.py
│       ├── st_diagnostics.py
│       ├── st_console.py
│       ├── setup_logging.py
│       ├── th_doc_reader.py       # list_doc / read_doc tools
│       ├── png_json_converter.py  # convert_png_to_json / convert_json_to_png / embed_cover_image / extract_cover_image / get_character_card_info
│       └── character_exploder.py  # explode_character_card / implode_character_card
├── docs/
│   ├── ST-API-Distilled/              # 11 distilled ST REST API doc files
│   ├── JS-Slash-Runner-Distilled/     # 21 distilled TH doc files
│   ├── ST-Prompt-Template-Distilled/  # 14 distilled STPT doc files
│   └── MagVarUpdate-Distilled/        # 11 distilled MVU doc files
├── pyproject.toml
├── LICENSE
└── README.md

中文

适用于 SillyTavern 的 MCP 服务器。让 AI 助手能直接在聊天界面中 创建角色卡、运行服务器诊断、读取控制台日志。

兼容任何 MCP 客户端：Claude Code、Cursor、Kilo、VS Code（通过 MCP 扩展）等。

不需要修改 SillyTavern 代码，不需要安装插件即可使用基础功能。配置好就能用。

基于 fastmcp + uv 构建。

工具列表

| 工具 | 功能 | |------|------| | write_character_card | 从文本属性（名称、人格、首条消息等）创建角色卡，生成 V2/V3 PNG 写入 characters 目录 | | import_character_card | 导入已有的角色卡 PNG 文件，原样复制不改元数据 | | get_st_diagnostics | 对运行中的 SillyTavern 做全面体检——API 连通性、角色卡完整性、聊天文件、配置、插件。零配置开箱即用 | | get_st_console | 读取 st-console-logger 插件捕获的 SillyTavern 控制台输出。支持增量读取 | | setup_st_logging | 一键安装控制台日志插件到 ST 的 plugins/ 目录，自动修改 config.yaml 启用服务器插件 | | list_doc | 列出所有可用的文档主题（TH、EJS 模板、MVU） | | read_doc | 按主题名称读取文档的完整内容 | | convert_png_to_json | 从角色卡 PNG 提取 V2/V3 元数据，保存为 .json 文件 | | convert_json_to_png | 从 .json 文件生成角色卡 PNG，支持内嵌/外部/默认头像 | | embed_cover_image | 将封面图以 base64 data URI 嵌入角色卡的 extensions.cover | | extract_cover_image | 从角色卡中提取封面图保存为图片文件 | | get_character_card_info | 读取角色卡 PNG 并返回元数据文本摘要 | | explode_character_card | 将大 JSON 角色卡拆分为按模块组织的多个 YAML/MD/JS/HTML 小文件，方便逐块编辑 | | implode_character_card | 将拆分后的角色卡目录重新拼回单个 JSON 文件 |

内置文档

本服务内置 57 篇蒸馏文档，覆盖四个 SillyTavern 框架：

| 框架 | 主题数 | 覆盖内容 | |------|--------|----------| | SillyTavern REST API | 11 | 角色卡、聊天、世界书、群组、AI 后端、分词器、设置、用户、扩展、多媒体、TTS/STT/搜索/SD | | JS-Slash-Runner (酒馆助手) | 21 | 脚本、宏、事件、角色、世界书、变量、正则、音频、预设、聊天消息、注入、扩展 | | ST-Prompt-Template (EJS 模板) | 14 | EJS 模板引擎、变量系统、注入、角色、预设、正则、工具函数、事件、世界书 | | MagVarUpdate (MVU 变量框架) | 11 | 变量状态管理、Schema 保护、更新命令、额外模型解析、清理、初始化、API |

AI 可直接参考这些文档来编写或调试脚本，无需离开聊天界面。

架构

MCP 客户端 (Claude Code / Cursor / Kilo / ...)
    │
    ▼
sillytavern-mcp (本项目) ←── 读写 ──→ ST 数据目录 (角色卡、日志文件)
    │
    └── 调用 ──→ SillyTavern HTTP API (状态查询、角色列表、CSRF)

安装

前置依赖： Python 3.11+ 和 uv

git clone <仓库地址> sillytavern-mcp
cd sillytavern-mcp
uv sync

MCP 客户端配置

根据你使用的 MCP 客户端，选择对应的配置方式。

方式 1：VS Code

在 .vscode/mcp.json 或 VS Code 的 MCP 设置中添加：

{
  "servers": {
    "sillytavern-mcp": {
      "type": "local",
      "command": ["uv", "run", "--directory", "D:\\path\\to\\sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
      "env": {
        "SILLYTAVERN_DATA_DIR": "D:\\path\\to\\SillyTavern\\data",
        "SILLYTAVERN_USER": "default-user",
        "SILLYTAVERN_URL": "http://localhost:8000"
      }
    }
  }
}

方式 2：Claude Code

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "sillytavern-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
      "env": {
        "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
        "SILLYTAVERN_USER": "default-user",
        "SILLYTAVERN_URL": "http://localhost:8000"
      }
    }
  }
}

方式 3：Cursor

在 Cursor 设置 → MCP Servers → 添加新服务：

{
  "name": "sillytavern-mcp",
  "type": "command",
  "command": "uv",
  "args": ["run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
  "env": {
    "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
    "SILLYTAVERN_USER": "default-user",
    "SILLYTAVERN_URL": "http://localhost:8000"
  }
}

方式 4：Kilo

在 ~/.config/kilo/kilo.json 中添加：

{
  "sillytavern-mcp": {
    "type": "local",
    "command": ["uv", "run", "--directory", "/path/to/sillytavern-mcp", "python", "-m", "sillytavern_mcp"],
    "environment": {
      "SILLYTAVERN_DATA_DIR": "/path/to/SillyTavern/data",
      "SILLYTAVERN_USER": "default-user",
      "SILLYTAVERN_URL": "http://localhost:8000"
    },
    "enabled": true
  }
}

快速测试

配置完成后，验证服务器能正常连接：

uv run python -m sillytavern_mcp

服务器会以 stdio 模式启动，等待客户端的 MCP 协议消息。没有输出即表示启动成功。

在你的 AI 助手中输入："检查一下我的 SillyTavern 的状态"

可选：启用控制台日志

想让你的 AI 助手能读取 SillyTavern 的控制台输出（错误信息、模型加载等）？

对 AI 助手说："帮我安装日志插件"

它会自动调用 setup_st_logging 完成：

将日志插件复制到 ST 的 plugins/ 目录
在 config.yaml 中启用服务器插件

然后重启 SillyTavern。重启后，控制台输出会自动写入 data/st_console.log，通过 get_st_console 工具即可读取。

全程不需要手动操作终端——助手会帮你做完。

配置说明

| 环境变量 | 默认值 | 说明 | |----------|--------|------| | SILLYTAVERN_DATA_DIR | 自动检测 | SillyTavern 的 data/ 目录路径 | | SILLYTAVERN_USER | default-user | SillyTavern 用户名 | | SILLYTAVERN_URL | http://localhost:8000 | SillyTavern HTTP API 地址 |

项目结构

sillytavern-mcp/
├── sillytavern_mcp/
│   ├── __init__.py              # FastMCP 实例
│   ├── __main__.py              # 启动入口 (python -m)
│   ├── server.py                # 工具 & 资源注册
│   ├── png_util.py              # PNG chunk 读写（角色卡格式）
│   ├── character_schema.py      # V2/V3 角色卡 JSON 构建
│   ├── default_avatar.py        # 无头像时的占位图生成
│   ├── st_client.py             # SillyTavern HTTP API 客户端
│   ├── utils.py                 # 共用函数、路径解析
│   ├── st_console_plugin/       # Node.js 服务端日志插件
│   │   ├── index.js
│   │   └── package.json
│   ├── resources/
│   │   ├── __init__.py
│   │   └── docs_distilled.py    # 57 篇文档资源 (docs://STAPI/*, docs://TH/*, docs://STPT/*, docs://MVU/*)
│   └── tools/
│       ├── write_character.py
│       ├── import_character.py
│       ├── st_diagnostics.py
│       ├── st_console.py
│       ├── setup_logging.py
│       ├── th_doc_reader.py     # list_doc / read_doc 工具
│       ├── png_json_converter.py  # PNG↔JSON 互转 & 封面嵌入/提取 工具
│       └── character_exploder.py  # explode_character_card / implode_character_card
├── docs/
│   ├── ST-API-Distilled/              # 11 篇蒸馏 ST REST API 文档
│   ├── JS-Slash-Runner-Distilled/     # 21 篇蒸馏 TH 文档
│   ├── ST-Prompt-Template-Distilled/  # 14 篇蒸馏 STPT 文档
│   └── MagVarUpdate-Distilled/        # 11 篇蒸馏 MVU 文档
├── pyproject.toml
├── LICENSE
└── README.md

License / 许可证

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), the same license as SillyTavern.

See the LICENSE file for details.

MCP Servers

sillytavern-mcp

English

Tools

Bundled Resources

Architecture

Setup

MCP Client Configuration

Option 1: VS Code

Option 2: Claude Code

Option 3: Cursor

Option 4: Kilo

Quick Test

Enable Console Logging (Optional)

Configuration Reference

Project Structure

中文

工具列表

内置文档

架构

安装

MCP 客户端配置

方式 1：VS Code

方式 2：Claude Code

方式 3：Cursor

方式 4：Kilo

快速测试

可选：启用控制台日志

配置说明

项目结构

License / 许可证

安装包（如果需要）

Cursor 配置 (mcp.json)

sillytavern-mcp

English

Tools

Bundled Resources

Architecture

Setup

MCP Client Configuration

Option 1: VS Code

Option 2: Claude Code

Option 3: Cursor

Option 4: Kilo

Quick Test

Enable Console Logging (Optional)

Configuration Reference

Project Structure

中文

工具列表

内置文档

架构

安装

MCP 客户端配置

方式 1：VS Code

方式 2：Claude Code

方式 3：Cursor

方式 4：Kilo

快速测试

可选：启用控制台日志

配置说明

项目结构

License / 许可证

安装包 （如果需要）

Cursor 配置 (mcp.json)

安装包（如果需要）