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: Chess MCP

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

Position Analysis

Move Evaluation

Simulation

Bearoff

Utility

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

Tests

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