Gensokyo

You run gensokyo as an MCP Server to bridge OneBot-v11 compatible bots to MCP clients. It enables you to connect a reverse WebSocket bot adapter and expose MCP endpoints for sending messages, receiving events, and coordinating with supporting ecosystems. This guide shows how to set up the server, connect a client, and start using MCP features with OneBot-v11 based plugins and tools.

How to use

Launch gensokyo to start the MCP Server. It will expose an MCP endpoint that you can connect to from your MCP clients (such as cline, vscode-cline, or other OneBot-v11 adapters). After wiring the connection, you can send messages, receive events, and utilize MCP routes to integrate existing OneBot-v11 plugins as tools in your workflow.

How to install

Prerequisites you need before installation: a supported operating system with a Go runtime for native implementations, plus any required tools your environment uses for MCP connections.

{
  "mcpServers": {
    "gensokyo_mcp": {
      "type": "http",
      "name": "gensokyo_mcp",
      "url": "http://127.0.0.1:8090/sse/sse",
      "args": []
    }
  }
}

Additional configuration and usage notes

After you start gensokyo, a configuration file named config.yml is generated automatically. Open this file to customize how you connect to your OneBot-v11 reverse WebSocket. The example below shows a typical HTTP MCP connection configured for a local address.

Configuration example

{
  "mcpServers": {
    "gensokyo-mcp": {
      "autoApprove": ["call_ws"],
      "disabled": false,
      "timeout": 30,
      "url": "http://127.0.0.1:8090/sse/sse",
      "transportType": "sse"
    }
  }
}

Troubleshooting and tips

If you encounter connection issues, verify that the MCP URL is reachable from your client host and that the OneBot-v11 reverse WebSocket endpoint is running. Check firewall rules, ensure the local port is not in use, and confirm that the MCP client is configured to point to the correct URL.

Notes on availability and scope

This server supports connecting multiple WebSocket addresses, virtualizing MCP user information into group and private chat events, and ongoing updates. It can route messages through various OneBot-v11 compatible plugins and ecosystems.

Available tools

send_group_msg

Sends MCP formatted group messages to connected OneBot-v11 plugins via the MCP server.

virtual_events

Extends event reporting by simulating group and private chat events for MCP clients.