MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

S
Sillytavern MCP
by @maurovideosmr-wq
GitHub Repo(1 stars)

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. No SillyTavern modifications needed. No plugins required for basic operation. Just configure and go.

Created 5/21/2026
Updated about 19 hours ago
README
View Source
Repository documentation and setup instructions

sillytavern-mcp

English | 中文

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:

  1. Copy the logger plugin to ST's plugins/ directory
  2. 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 完成：

  1. 将日志插件复制到 ST 的 plugins/ 目录
  2. 在 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.

Quick Setup
Installation guide for this server

Install Package (if required)

uvx sillytavern-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "maurovideosmr-wq-sillytavern-mcp": { "command": "uvx", "args": [ "sillytavern-mcp" ] } } }