KoikatuMCP
日本語 | English
A Model Context Protocol (MCP) server that enables AI assistants to control Koikatsu Studio through natural language commands.
Requirements
- Koikatsu (KK) or Koikatsu Sunshine (KKS)
- KKStudioSocket plugin
- LLM systems that operate as MCP clients, such as Claude
Installation
1. Install KKStudioSocket Plugin
Follow the KKStudioSocket installation guide to set up the WebSocket plugin.
2. Download KoikatuMCP
- Download the latest release from Releases
- Extract the ZIP file to any location
- The archive contains:
KoikatuMCP.exe (single executable file)README.md (this file)LICENSE (license information)
Setup with Claude Desktop
Add the following configuration to your Claude Desktop MCP settings:
Via Claude Desktop Settings
- Locate the path to
KoikatuMCP.exe (Right-click the KoikatuMCP.exe file inside the unzipped folder → Select "Copy as path")
- Open Claude Desktop
- Go to Settings → Developer → Edit Config
- A File Explorer window will open at
%APPDATA%\Claude. Open claude_desktop_config.json in a text editor.
- Add the following entry and save file:
{
"mcpServers": {
"koikatu-mcp": {
"command": "Paste the full path to KoikatuMCP.exe here",
"env": {
"KKSTUDIOSOCKET_URL": "ws://127.0.0.1:8765/ws"
}
}
}
}
⚠️ Note: Backslashes in the path must be escaped by doubling them.
Example:
❌ Incorrect: "C:\Users\user\Downloads\KoikatuMCP.exe"
✅ Correct: "C:\\Users\\user\\Downloads\\KoikatuMCP.exe"
Via Configuration File (e.g., Claude Code, Gemini CLI)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"koikatu-mcp": {
"command": "C:\\path\\to\\KoikatuMCP.exe"
}
}
}
Usage
1. Start Koikatsu Studio
- Launch Koikatsu or Koikatsu Sunshine Studio
- Ensure KKStudioSocket is active (WebSocket server running on port 8765)
You can verify whether KKStudioSocket is loaded correctly by checking for the following lines in output_log.txt:
[Info : BepInEx] Loading [KKStudioSocket 1.0.0]
[Info :KKStudioSocket] Awaking KKStudioSocket v1.0.0
2. Start Claude Desktop
With the MCP configuration in place, KoikatuMCP will automatically connect when you start a conversation.
3. Talk with yout LLM Chatbot
Connection Test
> 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!
Inspect Items Placed in the Scene
> 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**
... [View full README on GitHub](https://github.com/great-majority/KoikatuMCP#readme)
