Koikatu MCP

KoikatuMCP

日本语 |英语

 

一个模型上下文协议（MCP）服务器，使AI助手能够通过自然语言命令控制Koikatsu Studio。

需求

• Koikatsu（KK） 或 小胜阳光（KKS）
• K工作室插座 插件
• LLM系统 作为MCP客户端运行，如Claude

安装

1.安装KKStudioSocket插件

跟随 KK工作室插座安装指南 设置WebSocket插件。

2.下载KoikatuMCP

1. 从下载最新版本 发布
2. 将ZIP文件解压缩到任何位置
3. 档案包含：

- KoikatuMCP.exe （单个可执行文件） - README.md （此文件） - LICENSE （许可证信息）

使用Claude Desktop进行设置

将以下配置添加到您的Claude Desktop MCP设置中：

通过克劳德桌面设置

1. 找到路径 KoikatuMCP.exe （右键单击 KoikatuMCP.exe 解压缩文件夹中的文件→ 选择“复制为路径”）
2. 打开克劳德桌面
3. 首选 设置 → 开发者 → 编辑配置
4. 文件资源管理器窗口将在以下位置打开 %APPDATA%\Claude.打开 claude_desktop_config.json 在文本编辑器中。
5. 添加以下条目并保存文件：

{
  "mcpServers": {
    "koikatu-mcp": {
      "command": "Paste the full path to KoikatuMCP.exe here",
      "env": {
        "KKSTUDIOSOCKET_URL": "ws://127.0.0.1:8765/ws"
      }
    }
  }
}

⚠️ 注意：路径中的反斜杠必须通过加倍来转义。 例子：

❌ Incorrect: "C:\Users\user\Downloads\KoikatuMCP.exe"  
✅ Correct: "C:\\Users\\user\\Downloads\\KoikatuMCP.exe"

通过配置文件（例如，Claude Code、Gemini CLI）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "koikatu-mcp": {
      "command": "C:\\path\\to\\KoikatuMCP.exe"
    }
  }
}

用法

开始 Koikatsu Studio

1. 推出小胜或小胜阳光工作室
2. 确保KKStudioSocket处于活动状态（WebSocket服务器在端口8765上运行）

您可以通过检查中的以下行来验证KKStudioSocket是否正确加载 output_log.txt:

[Info   :   BepInEx] Loading [KKStudioSocket 1.0.0]
[Info   :KKStudioSocket] Awaking KKStudioSocket v1.0.0

2.启动克劳德桌面

在MCP配置就绪的情况下，KoikatuMCP将在您开始对话时自动连接。

3.与你交谈LLM聊天机器人

连接测试

> Please run a ping to check the connection!

● Executing connection check to KKStudioSocket!

● `koikatu-mcp:ping` (MCP) (message: "Connection test")
  ⎿  ✅ Ping successful! Server responded with: Connection test

● ✅ Connection successful!

  The connection to KKStudioSocket has been successfully established.  
  The WebSocket server is functioning correctly, and KoikatuMCP is now able to communicate with Koikatsu Studio.

  You can now use all available features, including scene manipulation, item placement, and camera control!

检查场景中放置的物品

> What items are currently placed in the scene?

● To check which items are placed in the current scene, let's retrieve the scene tree.

● `koikatu-mcp:tree` (MCP) (depth: 2)  
  ⎿  🌲 Scene Tree:  
     📦 Folder (ID: 127, Type: OCIFolder)  
        🎯 Position: (3.79, -1.54, -16.95)  
     … +821 lines (ctrl+r to expand)

● The following items are currently placed in the scene:

  **Main Objects**

  1. **Character**

  - Haruka Shinozaki (ID: 0) – Female character  
    - Position: (0.00, 0.00, 0.00)

  2. **Item**

...

可用命令

场景管理

• 添加对象（项目、灯光、相机、角色）
• 修改对象属性（位置、旋转、比例、颜色）
• 从场景中删除对象
• 获取场景层次和结构

相机控制

• 定位和定向摄像头
• 在相机视图之间切换
• 截图

内容发现

• 浏览可用商品目录
• 搜索特定项目
• 获取详细的商品信息

对象操纵

• 附着/分离对象以创建层次结构
• 修改可见性和外观
• 调整照明属性

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

链接

• KKStudioSocket 插件
• 模型上下文协议
• 贡献指南