🤖 MCP 支持

Misaka 弹幕库从 v2.7.2 开始内置 MCP Server，可以让支持 MCP 的 AI Agent 通过自然语言调用弹幕库的外部控制能力。

功能定位

MCP 支持基于现有的 外部控制 API 实现。它不是新的播放器弹幕接口，而是给 Claude、Cursor、Cline 等 AI 工具使用的控制入口。

使用前准备

使用 MCP 前，请先完成外部控制配置：

1. 进入 Web UI 的 外部控制 页面
2. 启用外部控制
3. 获取或生成 API 密钥
4. 确认客户端可以访问 Misaka 服务地址

连接地址

MCP Server 的默认端点为：

协议://服务地址:7768/api/mcp

请根据实际部署方式将 协议 替换为 http 或 https。

传输协议为：

Streamable HTTP

认证方式

MCP 使用的密钥与 外部控制 API 密钥 相同。

推荐使用请求头认证：

X-API-KEY: <你的外部控制API密钥>

也兼容查询参数方式：

协议://服务地址:7768/api/mcp?apikey=你的外部控制API密钥

安全提醒

不要把外部控制 API 密钥公开到群聊、截图或公开仓库中。MCP 可以调用外部控制能力，建议只在可信网络或反代鉴权后使用。

客户端配置示例

将下面配置加入支持 MCP 的客户端中，并替换服务地址和 API 密钥：

{
  "mcpServers": {
    "misaka-danmu": {
      "type": "http",
      "url": "协议://服务地址:7768/api/mcp",
      "headers": {
        "X-API-KEY": "你的外部控制API密钥"
      }
    }
  }
}

请将 协议 替换为 http 或 https，并将 服务地址 替换为实际可访问的域名或 IP。

可用工具范围

MCP 会把外部控制 API 暴露为 AI Agent 可调用的工具，主要包括：

搜索与导入

• 搜索媒体
• 全自动搜索并导入
• 直接导入搜索结果
• 编辑后导入
• XML 导入
• URL 导入
• 获取搜索结果分集列表

媒体库管理

• 获取或搜索媒体库
• 获取作品详情
• 获取作品数据源和分集列表
• 创建、编辑、删除作品
• 添加或删除数据源
• 编辑或删除分集
• 刷新分集弹幕

Token 管理

• 获取 Token 列表
• 创建、更新、删除 Token
• 启用或禁用 Token
• 重置 Token 调用次数
• 查看 Token 访问日志

任务与定时任务

• 获取后台任务列表
• 查看单个任务状态
• 中止、暂停、恢复任务
• 获取定时任务列表
• 获取定时任务最近运行结果

配置与弹幕源

• 获取弹幕输出设置
• 更新弹幕输出设置
• 获取可配置参数
• 更新指定配置项
• 获取所有弹幕源配置
• 更新单个弹幕源配置

日志与监控

• 获取实时日志
• 获取历史日志文件列表
• 读取指定历史日志文件
• 获取流控状态

v2.7.2 相关增强

外部控制接口扩展

v2.7.2 新增了弹幕源配置与日志相关外部控制接口，MCP 也可以调用这些能力：

接口	方法	说明
/api/control/scrapers	GET	获取所有已加载弹幕源配置
/api/control/scrapers/{provider}	PUT	更新指定弹幕源配置
/api/control/logs	GET	获取实时日志
/api/control/logs/files	GET	获取历史日志文件列表
/api/control/logs/files/{filename}	GET	读取指定历史日志文件

外部控制日志接入

所有通过 MCP 的访问都会写入外部控制日志，并带有 MCP: 前缀，方便排查：

• API Key 是否缺失
• API Key 是否无效
• 请求体和响应体记录
• 状态码记录
• 调用来源 IP

常见问题

连接后提示 401

通常是 API 密钥没有传对，请检查：

• 是否已启用外部控制
• X-API-KEY 是否填写正确
• 是否复制成了弹幕 Token，而不是外部控制 API 密钥

访问 /api/mcp 返回 404

请确认服务版本为 v2.7.2 或更新版本。旧版本没有内置 MCP Server。

工具列表为空或调用失败

MCP 只暴露外部控制 API 下的工具，请确认外部控制功能正常，并优先访问内置 Swagger 文档检查接口是否可用：

协议://服务地址:7768/api/docs