home / mcp / shogi mcp server

Shogi MCP Server

Provides an HTTP bridge for analysis and an MCP server for engine integration and multiple‑PV evaluation.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "azumausu-shogi-mcp": {
      "command": "npm",
      "args": [
        "run",
        "start:mcp"
      ],
      "env": {
        "PORT": "8787",
        "DEBUG": "1",
        "EVAL_DIR": "./eval",
        "EVAL_FILE": "./eval/nn.bin",
        "REST_BASE": "http://localhost:8787",
        "ENGINE_PATH": "./engine/engine"
      }
    }
  }
}

You run a dedicated MCP server that hosts a Shogi AI agent and exposes two interfaces: an HTTP bridge for board analysis and an MCP server for agent integration. This setup lets clients analyze positions, request multi‑pv evaluations, and perform post‑move evaluations through a consistent MCP protocol while keeping the engine interactions encapsulated behind stable endpoints.

How to use

You will use two main components: the HTTP bridge to analyze positions and the MCP server to expose AI actions to MCP clients. Start the bridge and the MCP server, then point your MCP client at the local endpoints. The bridge provides a health check and an analyze endpoint, while the MCP server offers commands to ping, analyze, and evaluate after a move.

To connect from a client, set up the MCP configuration so that the MCP client can spawn and talk to the local MCP server process. You specify the full path to the Node executable, the path to the MCP server script, and the REST base URL the MCP server should use to reach the bridge.

How to install

Prerequisites you need before installation: Node.js 18.0.0 or newer, a USI protocol compatible Shogi engine, and an evaluation function file (nn.bin). Install and run the server components following these steps.

# Clone the project
git clone <repository-url>
cd shogi-mcp

# Install dependencies
npm install

Additional sections

Configuration and startup details follow. You will place the engine binary and evaluation file in the expected paths and then start both the bridge and the MCP server. The bridge serves at port 8787 by default and exposes health and analyze endpoints. The MCP server uses stdio communication for MCP clients and provides tools to ping, analyze, and evaluate after a move.

Configuration snippets you will use in your client setup include the MCP server entry that runs the MCP server process and the environment variable REST_BASE used to reach the bridge.

Bridge startup and health checks

# Start the bridge (HTTP API bridge)
npm run start:bridge

# Bridge defaults to port 8787

Troubleshooting and notes

If you run into problems with the evaluation function not loading, specify the path explicitly through environment variables and restart the bridge.

If the engine fails to start, ensure the engine binary has execution permissions and that the ENGINE_PATH points to a valid USI engine.

Development tips include using the provided health and analyze endpoints to verify that the bridge is connected to the engine and that position analysis works as expected.

Available tools

ping

Check connectivity with the MCP server to ensure the channel is alive and responsive.

analyze

Request a full analysis of the current position, including multiple principal variations (MultiPV) and evaluation scores.

eval_at

Evaluate the position after a specific move to assess the resulting board state.