Skip to main content
Glama
Sign In
bb-gnubg-mcp

bb-gnubg-mcp

by hbomze
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

bb-gnubg-mcp

MCP server wrapping the GNU Backgammon neural network evaluation engine. Exposes 18 tools for position analysis, move evaluation, rollouts, and board conversion via the Model Context Protocol.

Requirements

  • Python 3.13+

  • uv

Related MCP server: Leela MCP Server

Installation

git clone <repo-url>
cd bb-gnubg-mcp
uv sync

Running Locally (stdio)

The default transport is stdio, suitable for use with Claude Code and other MCP clients:

uv run python -m bb_gnubg_mcp

Or via the installed script:

uv run bb-gnubg-mcp

Claude Code Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "bb-gnubg-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bb-gnubg-mcp", "python", "-m", "bb_gnubg_mcp"]
    }
  }
}

Running Locally (HTTP)

For HTTP transport with API key authentication:

export MCP_TRANSPORT=http
export API_KEY=your-secret-key
export PORT=8000  # optional, defaults to 8000
uv run python -m bb_gnubg_mcp

The server starts on http://0.0.0.0:8000 with:

  • Streamable HTTP MCP transport

  • Bearer token auth on all tool calls (pass Authorization: Bearer <API_KEY>)

  • Health check at GET /health

Docker

Build

docker build -t bb-gnubg-mcp .

Run

docker run -p 10000:10000 \
  -e API_KEY=your-secret-key \
  bb-gnubg-mcp

The Dockerfile uses a multi-stage build with uv. The image defaults to HTTP transport on port 10000.

Override settings

docker run -p 8080:8080 \
  -e API_KEY=your-secret-key \
  -e PORT=8080 \
  -e MAX_ROLLOUT_GAMES=5000 \
  bb-gnubg-mcp

Deploy to Render

  1. Push this repo to GitHub.

  2. In the Render dashboard, click New > Blueprint and connect your GitHub repo.

  3. Render detects render.yaml and creates the service automatically.

  4. Set the API_KEY environment variable in the Render dashboard (it's marked sync: false in the Blueprint so it won't be committed to source).

  5. Deploy. The health check at /health confirms the service is running.

Alternatively, create the service manually:

  1. New > Web Service in Render.

  2. Connect your GitHub repo.

  3. Set Environment to Docker.

  4. Add environment variables:

    • MCP_TRANSPORT = http

    • PORT = 10000

    • API_KEY = your secret key

  5. Set Health Check Path to /health.

  6. Deploy.

Auto-deploy is enabled — pushing to the connected branch triggers a new deployment.

Tools

Board Conversion

Tool

Description

board_from_position_id

Position ID string to 2x25 board

board_from_position_key

Position key string to 2x25 board

position_id

Board (any format) to Position ID

key_of_board

Board (any format) to position key

Position Analysis

Tool

Description

classify

Classify position type (contact, race, bearoff, etc.)

probabilities

Win/gammon/backgammon probabilities via neural net

pub_eval_score

Fast heuristic evaluation score

Move Evaluation

Tool

Description

best_move

Best move with alternatives, probabilities, and equity

pub_best_move

Best move via fast public evaluation

moves

All legal moves for a position and dice roll

Simulation

Tool

Description

rollout

Cubeless Monte Carlo rollout

cubeful_rollout

Cubeful Monte Carlo rollout

Bearoff

Tool

Description

bearoff_id_2_pos

Bearoff ID to 6-point position

bearoff_probabilities

Probability distribution for bearing off in N moves

one_checker_race

Win probability for single-checker bearoff

Utility

Tool

Description

roll

Roll two dice

equities_value

Match equity table lookup

get_constants

List all GNUBG constant names and values

Board Input Formats

All tools that accept a board position support three formats:

JSON boardState (matching the bb-plays-mcp convention):

{
  "board": {
    "x": {"24": 2, "13": 5, "8": 3, "6": 5},
    "o": {"24": 2, "13": 5, "8": 3, "6": 5}
  },
  "player": "x"
}

Position ID (14-character GNUBG string):

"4HPwATDgc/ABMA"

Raw 2x25 array (as returned by gnubg):

[[0,0,0,0,0,5,0,3,0,0,0,0,5,0,0,0,0,0,0,0,0,0,0,2,0],
 [0,0,0,0,0,5,0,3,0,0,0,0,5,0,0,0,0,0,0,0,0,0,0,2,0]]

Environment Variables

Variable

Default

Description

MCP_TRANSPORT

stdio

Transport mode: stdio or http

API_KEY

—

Required for HTTP mode. Bearer token for auth.

PORT

8000

HTTP listen port

MAX_ROLLOUT_GAMES

10000

Maximum games per rollout call

Tests

uv run pytest                    # all tests (rollouts are slow)
uv run pytest -m "not slow"      # skip rollout tests

Available Tools

18 tools
bearoff_id_2_posC

Convert a bearoff ID to a 6-point position tuple.

Args: bearoff_id: Either an integer bearoff ID or a 6-element list.

Returns: Dict with the 6-point position (checkers on points 1-6).

Inputs: bearoff_id (required). Returns: object

bearoff_probabilitiesC

Get the probability distribution of bearing off in N moves.

Args: bearoff_id: Either an integer bearoff ID or a 6-element list.

Returns: Dict with probability distribution of bearing off in 1, 2, ..., N moves.

Inputs: bearoff_id (required). Returns: object

best_moveA

Find the best move for a position and dice roll using neural network evaluation.

Args: board_input: Board in any supported format. dice: Dice roll as [die1, die2], each 1-6. player: Who is on roll ("x" or "o"). Default "x". ply: Evaluation depth (0, 1, or 2). Higher is stronger but slower. score: Match score as [x_away, o_away]. Omit for money game. cube: Cube state as {"owner": "C"/"X"/"O", "value": 1, "centered": true}. seed: RNG seed for reproducibility.

Returns: Dict with best_move notation, alternatives with probabilities, and board after move.

Inputs: dice (required), board_input (required), ply, cube, +3 more. Returns: object

board_from_position_idA

Convert a 14-character GNUBG Position ID to a board representation.

Args: position_id: A 14-character GNUBG Position ID string (e.g. "4HPwATDgc/ABMA").

Returns: Dict with the 2x25 board array and the position ID.

Inputs: position_id (required). Returns: object

board_from_position_keyA

Convert a GNUBG position key string to a board representation.

Args: position_key: A GNUBG position key string.

Returns: Dict with the 2x25 board array, position ID, and key.

Inputs: position_key (required). Returns: object

classifyA

Classify a board position into one of GNUBG's position types.

Args: board_input: Board in any supported format. player: Who is on roll ("x" or "o"). Required if board_input is a boardState dict.

Returns: Dict with classification name and numeric code. Classifications: "over", "bearoff", "race", "crashed", "contact".

Inputs: board_input (required), player. Returns: object

cubeful_rolloutA

Perform a cubeful rollout with doubling cube handling.

Args: board_input: Board in any supported format. player: Who is on roll ("x" or "o"). Default "x". ngames: Number of games to simulate (default 576, max configurable). ply: Evaluation depth (0, 1, or 2). score: Match score as [x_away, o_away]. Omit for money game. cube: Cube state dict. seed: RNG seed for reproducibility.

Returns: Dict with detailed rollout statistics including cubeful equity.

Inputs: board_input (required), ply, cube, seed, +3 more. Returns: object

equities_valueA

Look up match equity for a given match score.

Args: x_away: Points player X needs to win the match (0-25). o_away: Points player O needs to win the match (0-25).

Returns: Dict with match winning chance (MWC) for player X.

Inputs: o_away (required), x_away (required). Returns: object

get_constantsA

Get all GNUBG constant values used by other tools.

Returns: Dict with position_classes, evaluation_modes, and rollout_types. Use these string names as parameter values in other tools.

Inputs: no named parameters. Returns: object

key_of_boardA

Convert a board to its GNUBG position key string.

Args: board_input: Board in any supported format. player: Who is on roll ("x" or "o"). Required if board_input is a boardState dict.

Returns: Dict with the position key string.

Inputs: board_input (required), player. Returns: object

movesA

Generate all legal moves for a board and dice roll.

Args: board_input: Board in any supported format. dice: Dice roll as [die1, die2], each 1-6. player: Who is on roll ("x" or "o"). Default "x".

Returns: Dict with list of legal moves, each with notation, steps, and position key.

Inputs: dice (required), board_input (required), player. Returns: object

one_checker_raceA

Estimate win probability for a one-checker bearoff race.

Args: pips: Number of pips remaining to bear off a single checker.

Returns: Dict with equity and standard deviation, or null if unsupported.

Inputs: pips (required). Returns: object

position_idA

Convert a board to its 14-character GNUBG Position ID.

Args: board_input: Board in any supported format (boardState dict, Position ID string, or 2x25 list). player: Who is on roll ("x" or "o"). Required if board_input is a boardState dict.

Returns: Dict with the position ID string.

Inputs: board_input (required), player. Returns: object

probabilitiesB

Calculate win/gammon/backgammon probabilities for a position.

Args: board_input: Board in any supported format. evaluation_mode: Evaluation strategy. One of: "prune", "race", "osr", "bearoff", "0plus1", "1sbear", "1srace". player: Who is on roll ("x" or "o"). Required if board_input is a boardState dict. nr: Number of rollouts for OSR mode (default 1296). score: Match score as [x_away, o_away]. Omit for money game. cube: Cube state as {"owner": "C"/"X"/"O", "value": 1, "centered": true}. seed: RNG seed for reproducibility.

Returns: Dict with win, win_gammon, win_backgammon, lose_gammon, lose_backgammon probabilities.

Inputs: board_input (required), nr, cube, seed, +3 more. Returns: object

pub_best_moveA

Find the best move using GNUBG's public (non-neural, fast) evaluation.

Args: board_input: Board in any supported format. dice: Dice roll as [die1, die2], each 1-6. player: Who is on roll ("x" or "o"). Default "x".

Returns: Dict with move as from/to pairs and notation.

Inputs: dice (required), board_input (required), player. Returns: object

pub_eval_scoreA

Compute a fast heuristic evaluation score using GNUBG's public (non-neural) model.

Args: board_input: Board in any supported format. player: Who is on roll ("x" or "o"). Required if board_input is a boardState dict.

Returns: Dict with the evaluation score. Positive favors the mover, negative favors opponent.

Inputs: board_input (required), player. Returns: object

rollA

Simulate a roll of two six-sided dice.

Returns: Dict with die1 and die2 values (1-6 each).

Inputs: no named parameters. Returns: object

rolloutA

Perform a cubeless Monte Carlo rollout of a position.

Args: board_input: Board in any supported format. player: Who is on roll ("x" or "o"). Default "x". ngames: Number of games to simulate (default 1296, max configurable). ply: Evaluation depth per move (0, 1, or 2). rollout_type: Rollout mode: "auto", "race", "bearoff", "over". score: Match score as [x_away, o_away]. Omit for money game. cube: Cube state dict. seed: RNG seed for reproducibility.

Returns: Dict with win probabilities and standard deviations.

Inputs: board_input (required), ply, cube, seed, +4 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 18 tools

    Disambiguation4/5

    The four board/position conversion tools (board_from_position_id, position_id, key_of_board, board_from_position_key) are clearly paired but could be misselected due to similar naming. Other tools like best_move vs pub_best_move and rollout vs cubeful_rollout are distinct but share comparable names, though descriptions help.

    Naming Consistency3/5

    Tool names use a mix of conventions: verb_noun (get_constants), noun phrases (best_move, probabilities), and abbreviations (bearoff_id_2_pos, pub_eval_score). No consistent verb pattern is present, but names are descriptive and readable.

    Tool Count3/5

    With 18 tools, the server is on the heavy side, exceeding the typical 3-15 well-scoped range. However, each tool serves a distinct backgammon analysis function, so the count is justified by the broad domain.

    Completeness5/5

    The tool set covers position representation, evaluation, move generation, rollouts, bearoff, and match equity—a complete lifecycle for backgammon analysis. There are no obvious dead ends or missing critical operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Chess MCP

      arvid-berndtsson
      A
      license
      Not graded
      quality
      D
      maintenance
      A powerful chess engine and game server built with the Model Context Protocol (MCP). Play chess against AI, analyze positions, and integrate chess functionality into your AI applications.
      48 npm
      1
      ISC

    • Stockfish MCP Server

      indulge
      F
      license
      A
      quality
      D
      maintenance
      Enables chess analysis and move generation using the Stockfish engine via MCP tools, allowing clients to evaluate positions, get best moves, apply moves, and visualize boards.
      7
      -

    • llm-chess-mcp

      prepaser
      A
      license
      A
      quality
      B
      maintenance
      MCP chess runtime that lets LLMs play, analyze, and adapt strength by exposing Stockfish, human move likelihood (Maia3), and Lichess statistics, with the LLM handling strategy and the server handling computation.
      13
      31 npm
      AGPL 3.0