KoikatuMCP by great-majority - MCP Server

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**

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

  2. **Item**

...

Available Commands

Scene Management

Add objects (items, lights, cameras, characters)
Modify object properties (position, rotation, scale, color)
Remove objects from the scene
Get scene hierarchy and structure

Camera Control

Position and orient the camera
Switch between camera views
Capture screenshots

Content Discovery

Browse available item catalogs
Search for specific items
Get detailed item information

Object Manipulation

Attach/detach objects to create hierarchies
Modify visibility and appearance
Adjust lighting properties

License

This project is licensed under the MIT License - see the file for details.

great-majority/KoikatuMCP