AI Client Integration (MCP)

MCP is a common protocol that lets AI clients (Claude Desktop, Claude Code, Cursor, GitHub Copilot in VS Code, Gemini CLI, Codex CLI and others) call external tools. Once you register the ShogiBoardQ server (shogiboardq-mcp), requests such as "convert this record to CSA", "analyse this position for 10 seconds" or "generate five mate-in-three puzzles" are carried out by the client through ShogiBoardQ's own functions.

The server connects with both the latest MCP specification (2026-07-28) and the earlier revisions (2024-11-05 to 2025-11-25), so it works with new and older clients alike.

These tools run shogiboardq-cli under the hood and do not need the window to be open.

Output of render_board_image: the same piece images and colours as the GUI, with the last move highlighted. Labels such as the turn badge and the rank coordinates follow the interface language and move notation set in ShogiBoardQ

When ShogiBoardQ is started with --automation, these tools read and change what the window shows.

Resources are provided for the current position (shogiboardq://position/current, SFEN), the current record (shogiboardq://kifu/current, KIF text) and the registered engines (shogiboardq://engines).

The examples below are for Linux; replace /path/to/ShogiBoardQ with your checkout. On Windows use python instead of python3 and paths such as C:\\Users\\...\\ShogiBoardQ\\build\\ShogiBoardQ.exe. Restart the client (or reload its MCP servers) after editing the configuration.

Run the following inside your project (add --scope user to enable it in every project). Everything after -- is the server command.

claude mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

claude mcp list      # check the connection

Add the server to claude_desktop_config.json, opened via Settings → Developer → Edit Config (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

Write it to .cursor/mcp.json in the project, or ~/.cursor/mcp.json for all projects.

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

Write it to .vscode/mcp.json in the workspace. VS Code uses servers as the top-level key. For a user-wide setup use the "MCP: Open User Configuration" command and the same format.

{
  "servers": {
    "shogiboardq": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

Register it with the command below, or add it to mcpServers in ~/.gemini/settings.json (or the project's .gemini/settings.json).

gemini mcp add -s user \
  -e SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  -e PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  shogiboardq python3 -m shogiboardq_mcp

{
  "mcpServers": {
    "shogiboardq": {
      "command": "python3",
      "args": ["-m", "shogiboardq_mcp"],
      "env": {
        "SHOGIBOARDQ_EXECUTABLE": "/path/to/ShogiBoardQ/build/ShogiBoardQ",
        "PYTHONPATH": "/path/to/ShogiBoardQ/mcp"
      }
    }
  }
}

Codex clients on the same host share ~/.codex/config.toml. Register the server with the command below, or add the configuration shown here. Use the Python interpreter where the mcp package is installed; for a virtual environment, replace python3 with its absolute path.

codex mcp add shogiboardq \
  --env SHOGIBOARDQ_EXECUTABLE=/path/to/ShogiBoardQ/build/ShogiBoardQ \
  --env PYTHONPATH=/path/to/ShogiBoardQ/mcp \
  -- python3 -m shogiboardq_mcp

[mcp_servers.shogiboardq]
command = "python3"
args = ["-m", "shogiboardq_mcp"]
startup_timeout_sec = 30
env_vars = ["DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "XDG_CONFIG_HOME"]

[mcp_servers.shogiboardq.env]
SHOGIBOARDQ_EXECUTABLE = "/path/to/ShogiBoardQ/build/ShogiBoardQ"
PYTHONPATH = "/path/to/ShogiBoardQ/mcp"

To launch the GUI automatically on Linux, add the env_vars line to [mcp_servers.shogiboardq] even when registering with the command. This forwards the display and session environment and the settings directory. Edit the existing table instead of adding a duplicate.

Check the registration with codex mcp get shogiboardq, then restart Codex and start a new conversation. In the CLI, use /mcp to check the connection. Ask “Use ShogiBoardQ's validate_sfen to validate startpos”; a legal move count of 30 confirms that the tool works. codex mcp list only shows the registration.

To try app tools without a display, add QT_QPA_PLATFORM = "offscreen" under [mcp_servers.shogiboardq.env]. The window will not appear on screen in this mode. See the official OpenAI MCP documentation for configuration details.

The automation API is off by default. Started with --automation, ShogiBoardQ accepts requests on a local socket that only your user can access and prints automation: listening on .... When SHOGIBOARDQ_EXECUTABLE is set, the server launches the app on the first GUI tool call (or connects to an instance that is already running).

./build/ShogiBoardQ --automation
# with an explicit socket location
./build/ShogiBoardQ --automation --automation-socket /tmp/shogiboardq.sock

Loading a record or setting a position while the current record has unsaved changes is refused unless discard_unsaved is passed explicitly. Menu actions are allow-listed: quitting and overwriting the current file cannot be triggered. Language changes are available and take effect after restarting the app. list_actions shows what is available.

Every tool names the window or dialog to operate with target (objectName, selector or part of the title); when omitted, it is the main window. Use the selector returned by get_widget_text or list_dialogs as widget or target to operate unnamed controls. Fetch it again after reopening the dialog or restarting the app. set_widget_value supports sliders, lists, checkable groups and colors; list_menu_actions provides the index paths for select_menu_action.

Tools that operate the screen wait until the app has performed the operation before returning, and return an error when it could not be performed at that time (the target was hidden, disabled or blocked by another dialog, for example). The state in the result tells whether the operation was performed (done), whether a modal dialog it opened is still open (running), or whether it was not performed while waiting (pending). When a tool fails, the message starts with an error kind shared with the CLI and the automation API, such as invalid_argument, not_found, file_exists or parse_error.