boardsesh-mcp

An unofficial MCP server that lets your AI agent read and analyse your Boardsesh climbing logbook — across every board you climb on: Kilter, Tension, MoonBoard, Decoy, Touchstone, So iLL, Woods and spray walls.

How did my last session go? Am I stronger on Kilter or on Tension? What are my projects at 40°? What should I try next at my level? Show my grade pyramid. Which holds do I avoid?

Read-only. Nothing is ever written to your Boardsesh account.

You do not need to give it a password. Boardsesh serves your logbook publicly, so your display name alone unlocks most of it. Credentials are optional and only add the extras.

Add to your agent

Kiro

Open your MCP config (command palette → Kiro: Open user MCP config (JSON)) and add:

{
  "mcpServers": {
    "boardsesh": {
      "command": "uvx",
      "args": ["boardsesh-mcp"],
      "env": {
        "BOARDSESH_USER": "Your Boardsesh Display Name"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

That is the whole setup. BOARDSESH_USER is the display name on your Boardsesh profile (or your user id, if you prefer). Requires uv installed; uvx ships with it.

Other clients

Same three facts everywhere: command uvx, args ["boardsesh-mcp"], env BOARDSESH_USER. Copy-paste configs for Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI and Zed are in docs/clients.md.

Optional: unlock the rest

Four tools need to know which physical board setup you use (layout, size, hold sets), which Boardsesh only tells the logged-in owner. Add your Boardsesh login to enable them:

"env": {
  "BOARDSESH_USER": "Your Display Name",
  "BOARDSESH_EMAIL": "${BOARDSESH_EMAIL}",
  "BOARDSESH_PASSWORD": "${BOARDSESH_PASSWORD}"
}

Those four are boardsesh_recommend_climbs, boardsesh_search_climbs, boardsesh_find_similar_climbs and boardsesh_get_hold_heatmap. Everything else works without them. See how to set environment variables.

Optional: timezone

Sessions are grouped by calendar day in your timezone, detected from the machine running the server. If that is wrong, add "BOARDSESH_TIMEZONE": "Europe/Rome" (any IANA name).

Example questions

Summarise my Boardsesh logbook.
How did my last session go?
Compare my climbing on Kilter and Tension — where am I actually stronger?
What are my current projects, and which have I tried the most?
Show my grade pyramid and my flash rate per grade.
Have I improved over the last six months?
What should I try next at my level?
Find climbs similar to the one I sent yesterday.
Which holds show up most in climbs one grade above me?

Tools the agent gets

Works with just BOARDSESH_USER:

Needs BOARDSESH_EMAIL / BOARDSESH_PASSWORD:

How the data is interpreted

• One logbook entry is one climb, at one angle, on one board, at one time, with a number of tries. Entries are never deduplicated, so a climb can appear many times.
• status is authoritative: flash (sent first try), send (sent after attempts) or attempt (not sent). It is never inferred from try counts.
• A project is a (board, climb, angle) you have attempted but not sent. Sending it at another angle does not remove it.
• grade is the board's own grade and difficulty_id the raw id. Board grades are not comparable between boards, so boardsesh_grade — Boardsesh's cross-board normalised number — is what boardsesh_compare_boards uses. It is null when Boardsesh's confidence in it is not backed by real ascents.
• A "session" is one calendar day in your timezone.

Security and privacy

• In the default setup there is no secret to leak: only your public display name is configured, and everything it reads is what your Boardsesh profile already shows publicly.
• If you do add credentials, they are used once to obtain a token from Boardsesh's own login endpoint. Tokens live in memory for the life of the process and are never written to disk.
• Credentials and tokens never appear in tool output, logs or error messages.
• The server talks only to ws.boardsesh.com and www.boardsesh.com. No telemetry.
• Every tool is read-only, and the GraphQL layer can only send a fixed set of pinned read queries — there is no code path that could reach a mutation.
• Your logbook is fetched at most once a minute however many tools the agent calls.

Troubleshooting: run uvx boardsesh-mcp --check with the same environment variables set. It prints counts and configuration only, no entries and no secrets, so it is safe to paste into an issue.

Relationship to Boardsesh and to kilter-mcp

Boardsesh is an open-source (Apache-2.0) board-climbing app that aggregates logbooks across boards and publishes an API. This project is an independent MCP client for it, built at the suggestion of its maintainer, but it is not an official Boardsesh product and any bug here is mine, not theirs.

If you only climb on a Kilter Board and do not use Boardsesh, kilter-mcp talks to Kilter directly instead. boardsesh-mcp is the better choice if you use more than one board, because it can compare them.

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md. Security reports go through SECURITY.md.

License

MIT