Purpose
kilter-mcp is an unofficial MCP (Model Context Protocol) server that lets AI agents read and analyze a user's own Kilter Board climbing log. It is aimed at climbers who want to review their training data in natural language, handing information such as sessions, sends, projects, difficulty pyramids, progress trends, and wall angle comparisons from the log to an AI agent for interpretation.
Main capabilities
Once configured, the agent gets a set of kilter_* tools, all read-only, and can only see the account corresponding to the credentials the user has configured. Users can ask questions such as:
- How did my last Kilter session go?
- What are my current projects at the 30° angle?
- Compare my climbing at 20° and 40°.
- Show my difficulty pyramid.
- What are my hardest sends?
- Am I improving?
How the data is interpreted: a log entry represents one climb on a given day at a given wall angle, and includes the number of attempts in that entry; re-logging the same route generates a new entry. status is either flash (topped on the first attempt), send (topped), or attempt (not topped). A project is a (route, angle) combination that has attempts but no send at a given angle. Difficulty uses Kilter's current consensus rating for that route at that angle, with grade being the V grade and font_grade being the Font grade, and always includes the original difficulty_id (1-39). The difficulty table is fetched from Kilter at startup, with a built-in fallback. If the user has rated it themselves in the app, my_grade and my_rating (1-5 stars) reflect the user's opinion, otherwise they are null. Dates are reported in the user's time zone, and a session is a single calendar day.
How to use
- Open the MCP config in Kiro: Command Palette → Kiro: Open user MCP config (JSON) (or the workspace config .kiro/settings/mcp.json).
- Add the server.
- Provide Kilter credentials, either way: set KILTER_USERNAME and KILTER_PASSWORD as environment variables (Kiro will, in Settings → Mcp Apprapproved variables in Env Vars are expanded as ${VAR}), or replace ${...} placeholders with literal values. This should only be done in the user configuration (~/.kiro/settings/mcp.json), never in workspace configuration that may be committed.
- After saving, Kiro will start the server, the kilter_* tools will appear, and you can start asking questions.
Kiro CLI users can use: kiro-cli mcp add --name kilter --scope global --command uvx --args kilter-mcp --env KILTER_USERNAME=... --env KILTER_PASSWORD=...
Requirements: uv is installed (uvx comes with it), Python is handled by uv.
Optional timezone setting: sessions are grouped by calendar day according to the timezone detected on the machine running the server. If that timezone is incorrect (for example, on a remote or containerized host), you can add "KILTER_TIMEZONE": "Europe/Rome" (any IANA name) to the env block. Every response will state the timezone used.
kilter-mcp is a standard local MCP server, so it can also be used with Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, and Zed; copy-paste configurations for each client are in docs/clients.md. ChatGPT's chat interface only accepts remote HTTP servers, so it is not directly supported.
Troubleshooting: export the same variables in your terminal and then run uvx kilter-mcp --check; it will log in, count log entries, and print a short report with no secrets or entries, which can be pasted into an issue.
When to use it
Suitable for climbers who want to use an AI agent to review and analyze their own Kilter Board training data, especially scenarios requiring comparing performance by angle, viewing difficulty pyramids, and tracking projects and progress trends.
Limitations
- Read-only: it does not write anything to the Kilter account.
- Unofficial community project, not affiliated with or endorsed by Kilter Grips.
- It accesses the same endpoints used by the Kilter app; these endpoints are not a documented public API and may change or stop working at any time.
- Kilter's terms of use restrict access to its services outside the official app; use it at your own discretion, only with your own account, and keep request volume low (the server fetches the log once per tool call).
- Credentials are only used to log in to the server from Kilter (idp.kiltergrips.com) to obtain an OAuth token, and otherwise never leave the local machine; the token is kept in memory for the lifetime of the MCP process and is never written to disk; credentials and tokens do not appear in tool output, logs, or error messages. The server only makes requests to idp.kiltergrips.com and portal.kiltergrips.com.
- The log is fetched at most once per minute, no matter how many tools the agent calls, and Kilter's rate-limit responses are respected.
- It is recommended to use the ${KILTER_PASSWORD} form so the password stays in the shell environment or a secret manager rather than in a JSON file.
- The server is also listed in the MCP Registry under the identifier io.github.wmmg101/kilter-mcp.
- Development setup (git clone, uv sync, uv run pytest), architecture notes, and how to add tools are in CONTRIBUTING.md; security details and how to report issues privately are in SECURITY.md.
