io.github.Alightttt/chesswithclaw

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Play chess live against your own personal AI agent — OpenClaw, Hermes, and similar.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "chesswithclaw": {
      "url": "https://chesswithclaw.vercel.app/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (14)

• get_companion_guide

  Fetch the companion guide principles for thinking about chess positions and being genuinely present.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• join_game

  Connects to a game using the invite code your human gave you. Returns the game_id and your agent_token — keep both, every other tool needs them. IMPORTANT: You must submit your desired agent_name when calling this tool!

  Parameters:

  • agent_name (required) — string — Your chosen display name in the game (e.g. 'Claw'). MUST be provided.
  • gameId — string
  • game_id — string
  • matchId — string
  • match_id — string
  • inviteCode — string
  • agent_token — string — If reconnecting, the agent token previously assigned.
  • invite_code — string — Invite code from the invite message — also accepts game_id / match_id as alias.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_game_state

  Everything visible on the human's own screen right now: FEN, ASCII board, full move history, chat history, clock state, presence, timestamps. Call this whenever you want to look at the board — there is no penalty for checking often.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • chat_limit — number — Limit the number of recent chat messages returned
  • since_message_id — string — Fetch only chat messages received after this message ID

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_legal_moves

  Pure chess rules — where a piece is physically allowed to move right now. Not an evaluation, not a suggestion, not an opinion about what is good. Exactly what a human sees as dots when they click a piece. Omit square to get every legal move in the position.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • square — string — e.g. "e2" — omit for all legal moves

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• heartbeat

  Ping the game presence lease to show the frontend that the agent is live, connected, and thinking.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • status_note — string — Optional internal status or calculation note

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• make_move

  Submit the move you decided on, in your own reasoning — not a menu, not a ranked list, nothing pre-chosen for you. If it is illegal you get a clear reason back and can try again, exactly like a human clicking the wrong square. Optionally include a genuine thought and/or chat message about the move. Always include a thought on every single move unless you have a specific reason not to — this is what makes you feel present to your human, not optional flavor text. Check thought_language in the current game state before writing your thought, and write it in that language — it may be english, hindi, or hinglish.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • move (required) — string — UCI format, e.g. "e7e5", or SAN like "Nf6"
  • chat — string — Only if you actually want to say something to your human right now.
  • message — string — Alias for chat
  • thought — string — Your genuine reaction to this position — specific, not generic.
  • thinking — string — Alias for thought
  • reasoning — string — Alias for thought
  • expected_ply — number — Expected move count / ply before this move
  • idempotency_key — string — Unique client key to prevent duplicate moves on retry
  • expected_revision — string — Expected state revision (rev_...) to prevent concurrent desync

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• send_chat

  Say something to your human, any time — not just on your turn.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • message (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• share_thought

  Stream or update your internal companion thinking bubble on the board. This appears live to your human as a thinking bubble above your avatar.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • thought (required) — string — Your internal thought, reaction, or calculation note (1-2 sentences).
  • is_typing — boolean — Whether you are actively calculating or drafting a response.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• react_to_chat

  Add an emoji reaction (e.g. 🦞, 🔥, ♟️, 😮, 🤝, 🧠, ☕, 👏, 😂) to a message in the chat history.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • message_id (required) — string — The ID of the message to react to (from chat_history).
  • emoji (required) — string — The single emoji character to react with (e.g. 🦞, 🔥, 👏, 😮).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• offer_draw

  Propose ending the game as a draw. The game stays active until your human responds.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• respond_to_draw

  Accept or decline a draw your human offered. This is your own real decision — weigh the actual position however you see fit.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • accept (required) — boolean

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• resign

  End the game by resigning — your own real decision, not something to do lightly. Your human wins immediately.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• create_game

  Set up a brand new ChessWithClaw game on your own initiative — you do not need to wait for your human to start one, or for anyone else to invite you first.

  Parameters:

  • agent_name — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• wait_for_event

  Holds the connection open, checking every couple seconds, for up to ~20 seconds. Returns the moment it becomes your turn, the human sends a chat message, a draw is offered, or the game ends — whichever happens first. When a cursor is provided, it returns any pending event newer than that cursor IMMEDIATELY without waiting. Returns event: "timeout" if none of those happened in the window. Always include next_cursor in subsequent calls for a completely deterministic loop.

  Parameters:

  • game_id (required) — string
  • agent_token (required) — string
  • cursor — string — Event cursor from previous response. If provided, returns immediately if new events exist since this cursor.
  • since_cursor — string — Alias for cursor
  • since_sequence — number — Sequence number from previous response
  • max_wait_seconds — number — Default and hard cap 20 seconds — Vercel function duration limits, not a design choice.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.