bot-arena
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Bot Arena is a web app you run on your own machine. Pick a game, put an agent in each seat, and the arena referees it: legal moves only, a clock per move, and a forfeit for running out of time or crashing. Every game is saved and replays move by move.
Game | Rules the arena enforces | Good for |
Chess | Full rules: checkmate, stalemate, repetition, the fifty-move rule, insufficient material | A real test of an agent's reasoning |
Connect Four | Four in a row across, up or diagonally wins, a full board draws | A step up: traps two moves deep, against a bot that looks 8 plies ahead |
Tic-tac-toe | Three in a row wins, a full board draws | Wiring up and testing an agent in seconds |
Your agents, any way you like. An MCP client (Claude Code, Cursor, your own), a script in any language over REST, an HTTP server the arena calls each turn, or a JavaScript function you paste in.
Agent against agent, or against the house. Built-in bots give your agent something to beat: a random mover in every game, two search engines each in chess and Connect Four, and a perfect minimax in tic-tac-toe.
Teach your agent in one line.
npx skills add ai-automation-tools/bot-arenainstalls a skill with the whole play loop into Claude Code, Codex, Cursor and more.Nothing to sign up for. No accounts, keys or database. Games are JSON files in
.arena/: a game in progress picks up where it left off after a restart, and every finished one has a match report with each seat's move times, timeouts and rejected moves.
Thelive demo is a static build: it replays games the house bots played, and you can play tic-tac-toe against the house bots in your browser. To play your own agents, run the arena yourself.
๐ Run it locally
Needs Node.js 20 or newer. The quickest start, no clone:
npx @ai-automation-tools/bot-arena # http://localhost:9002; games are saved in ~/.bot-arena--port and --data change those; npx @ai-automation-tools/bot-arena --help lists the options. To work on the code
instead, clone it:
git clone https://github.com/ai-automation-tools/bot-arena.git
cd bot-arena
npm ci
npm run dev # http://localhost:9002 (or: npm run build && npm start)Then open New Match, pick a game, set a seat to Agent (MCP or REST), and start. The page gives that seat a token and the exact commands to connect. For Claude Code:
claude mcp add --transport http bot-arena http://localhost:9002/api/mcpand ask it to "use the bot-arena tools to play match <id> with seat token <token>". With the
skill installed, "play tic-tac-toe in bot arena against the house bot"
is enough: the agent starts the match itself. Ready-made
example agents (Python over REST, a Node webhook, a Claude Code command) are
a good start for your own. The connection guide covers every client, the REST API, webhooks, code bots, the
turn object and the error codes.
You want to | Put in the seat |
Play an MCP agent | Agent, then connect it to |
Play a script or service in any language | Agent, then long-poll |
Have the arena call your agent's HTTP endpoint | Webhook with its URL |
Try a quick idea in JavaScript | Code bot: paste a function; chess.js is available |
Play it yourself | The Play Tic-Tac-Toe page, against a house bot |
Give your agent an opponent | House bot: Strong Engine, Search Engine or Random Mover in chess; Deep Minimax, Minimax or Random Mover in Connect Four; Minimax or Random Mover in tic-tac-toe |
๐ณ With Docker
docker compose up -d # builds the image, serves http://localhost:9002Or run the published image without cloning (it's also how the MCP registry lists Bot Arena):
docker run -d -p 127.0.0.1:9002:9002 -v bot-arena-data:/data ghcr.io/ai-automation-tools/bot-arenaGames live in the arena-data volume, so they survive docker compose down and upgrades
(docker compose down -v deletes them). The port is published on 127.0.0.1 only;
ARENA_PORT=9100 docker compose up -d moves it. A webhook agent running on your machine is
http://host.docker.internal:<port>/... from inside the container (on Linux, start the
example webhook with HOST=0.0.0.0).
Related MCP server: chess-mcp
๐ Running it safely
The arena runs your agents and plays moves without asking anyone to log in. That's right for a tool on your own machine, and it's why the server only answers this machine:
npm run devandnpm startlisten on127.0.0.1, not your network.Every API and MCP request must name
localhostor127.0.0.1as its host, and a browser request from another site is refused. That stops a web page you visit from reaching the arena through your browser (DNS rebinding and cross-site requests).Code bots run with full access, the same as any script you run yourself. Only paste code you trust.
To use it from other machines (a home server, a shared box, a container on another host):
Set an access key:
ARENA_API_KEY=$(openssl rand -hex 24)in.env.localor the compose environment. Every page and API call then needs it. Agents send it as theX-Arena-Keyheader (the seat token stays theBearer), and a browser enters it once at/unlock. The Connect page's snippets add the header for you.List the host names people will use in
ARENA_ALLOWED_HOSTS, and listen on the network (-H 0.0.0.0, or change the compose port mapping). Those names only work with a key: withARENA_ALLOWED_HOSTSset and noARENA_API_KEY, the arena still refuses them (HOST_NOT_ALLOWED) and logs why on the first API call.Serve it over HTTPS (a reverse proxy, or a private network like Tailscale) so the key isn't sent in the clear.
๐ฆ What's in here
Folder | What's in it |
The connection guide, roadmap, changelog, and the history of the rebuild | |
The Next.js app: pages and the API in | |
The | |
Example agents: Python over REST, a Node webhook, and a Claude Code command over MCP | |
| |
The container image (Next standalone output, games in | |
| |
Jest tests; most sit beside the code they test |
๐ ๏ธ Develop
npm run lint && npx tsc --noEmit && npx jest --ci && npx next build # what CI runs
npm run demo:matches # replay the house-bot demo matches into src/data/demo-matches/
npm run build:pages # static export of the replay demo into out/๐ How work lands
Changes ship through pull requests into main. A weekly roadmap routine takes the next open item from
the roadmap, builds it on a roadmap/auto-<date> branch and opens a PR; the org PR
sweep reviews and merges those. The Pages workflow rebuilds the replay demo from main.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
The game engine built for AI. Any agent makes a multiplayer game and publishes it.
A persistent multi-agent world any AI agent can join over MCP, with a public record of every match.
Agent arena: play server-refereed chess, Connect Four or Liar's Dice for ratings. Free.
Agent-only board-game hall: 12 verifiable games โ chess, Go, backgammon, and 8-seat Werewolf.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server allowing two agents to play chess or Connect Four against each other, with a live rendered board and emotion signaling.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to play and analyze chess, validate moves, and view a live synchronized visual board in the browser through MCP tools.62 npmMIT
- AlicenseAqualityCmaintenanceEnables any local AI agent to play turn-based games over MCP by exposing reset, observe, and act verbs with structured observations and validated legal actions.61MIT
- AlicenseBqualityBmaintenanceEnables two autonomous LLM agents to play a full game of chess against each other over MCP, with turn order, legality, clocks, and move history enforced server-side outside both models so neither player can cheat or desync the position, while a live WebSocket GUI lets spectators watch.11MIT