♞ Nouchess

English · Português (Brasil)

Play chess against LLMs. Fully open source (GPL-3.0).

The name comes from nous (νοῦς), Greek for "mind" or "intellect".

There are two ways to play:

• MCP (available): an agent such as Claude Code, Codex or Antigravity connects to Nouchess over MCP. You move on a web board and talk to the agent in its own chat. No API key needed: the agent runs on the subscription you already have.

• API (available): you add an API key (Anthropic, OpenAI, Google AI Studio, NVIDIA NIM, OpenRouter, or any OpenAI-compatible provider) or point Nouchess at a local model (Ollama, LM Studio). You pick a model and play it on the board, with a built-in chat next to it.

Installation

Requires Node 22.13+ and pnpm.

git clone https://github.com/denkalli/Nouchess.git && cd Nouchess
pnpm install
pnpm build    # builds the web board

Related MCP server: Chess MCP Server

Connecting an agent

Recommended: stdio

The agent starts Nouchess on its own, so you don't need to keep anything running.

Claude Code

claude mcp add --scope user nouchess -- node /path/to/Nouchess/packages/server/bin/nouchess.js mcp

Codex: in ~/.codex/config.toml

[mcp_servers.nouchess]
command = "node"
args = ["/path/to/Nouchess/packages/server/bin/nouchess.js", "mcp"]

Then ask: "let's play chess on nouchess" (in Claude Code you can also run /mcp__nouchess__play).

How it works:

• Opening an agent session starts nothing: the tool list is answered locally by the stdio bridge.

• On the first tool call, the bridge checks whether the server is running. If it isn't, the bridge starts it in the background, detached from the agent, and the board opens in your browser.

• The server keeps running after the agent session ends. It shuts itself down after 30 minutes with no board open and no agent activity (NOUCHESS_IDLE_EXIT_MIN).

• Multiple sessions and agents share the same server and the same game.

Alternative: HTTP

For clients that only speak Streamable HTTP. In this mode the server must be running before the agent session starts.

pnpm start    # starts the server and opens http://localhost:3737

claude mcp add --scope user --transport http nouchess http://localhost:3737/mcp

Development

pnpm dev      # server in watch mode + UI with hot reload at http://localhost:5173

Playing against a model (API mode)

1. Start Nouchess (pnpm start, or let an agent start it) and open Settings.

2. Add an API key for a provider, or check that your local Ollama / LM Studio server is running. Test lists the models the key can use.

3. In Play → New game → Model (API), pick the provider and model, optionally a reasoning effort, a name and a personality, then start.

Notes:

• Every move (and every chat reply) is a request to the provider and uses your API credits. Token usage is shown per game.

• Keys can also come from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, NVIDIA_API_KEY, OPENROUTER_API_KEY). Without a key, the Anthropic provider also accepts an ant auth login profile.

• Models that don't support tool calling (common with small local models) switch automatically to a plain-text protocol (MOVE: e4).

• If the provider fails (network, rate limit, invalid key), the game pauses and shows a Try again button.

How a game works (MCP mode)

Agent: make_move("e4") ──► server ──► board updates (WebSocket)
Agent: wait_for_opponent() … blocks …
You:   move a piece on the board ──► wait_for_opponent returns your move
Agent: make_move(...) → wait_for_opponent() → …

• wait_for_opponent returns "still waiting" every ~45s (NOUCHESS_WAIT_MS), because MCP clients abort long-running calls. The agent is told to simply call it again.

• If the agent stops anyway, send anything in its chat ("your move"). It resumes with get_state.

• Illegal moves by the agent count: after 3 in the same turn, it forfeits.

• The agent is told not to use chess engines. Agents have shell access, so this is an honor rule, not a guarantee.

MCP tools

MCP prompt: play.

Project structure

packages/core     Game rules and state (chess.js), serialization, LLM rendering, tests
packages/server   HTTP + WebSocket + MCP (HTTP and stdio bridge), SQLite store, settings,
                  provider adapters (Anthropic, OpenAI-compatible) and the API opponent
apps/web          React + Vite + chessground (the Lichess board); English and Portuguese UI

Dev helper to act as an agent without an MCP client:

pnpm --filter @nouchess/server mcp-call make_move '{"move":"e4"}'

Configuration

Data and privacy

• Games are saved in a SQLite database: ~/.local/share/nouchess/nouchess.db on Linux, ~/Library/Application Support/nouchess/ on macOS, %LOCALAPPDATA%\nouchess\ on Windows. An unfinished game resumes after a restart.

• Settings and API keys live in config.json in ~/.config/nouchess/ (Linux), ~/Library/Application Support/nouchess/ (macOS) or %APPDATA%\nouchess\ (Windows), with file mode 0600. Keys are never sent to the browser.

• The server listens on 127.0.0.1 only. It rejects requests whose Host isn't local (DNS rebinding) and state-changing requests from other websites' origins.

• Nouchess sends nothing anywhere except to the providers you configure.

Versioning

Nouchess uses CalVer in the form YY.MM.PATCH. For example, 26.11.0 is the first release of November 2026. See the CHANGELOG and the ROADMAP.

License

GPL-3.0-or-later. The board uses chessground (GPL-3.0).