1. Install
One line, any OS. The installer detects your platform, downloads and checksum-verifies the binary, puts ryvem-mcp on your PATH, runs the setup wizard, and registers the server with any agent CLI it finds.
curl -fsSL https://ryvem-mcp.viniciusborges.dev/install.sh | bashirm https://ryvem-mcp.viniciusborges.dev/install.ps1 | iexThe binary lands per-user, and that directory is added to your PATH:
| Platform | Install path |
|---|---|
| macOS / Linux | ~/.local/bin/ryvem-mcp |
| Windows | %LOCALAPPDATA%\Programs\ryvem-mcp\ryvem-mcp.exe |
On macOS
The installer clears the Gatekeeper quarantine flag and ad-hoc-signs the binary, so it runs without prompts.
2. Run the setup wizard
After install, the wizard offers to configure a board and repository. It writes a secret-holding .env next to the binary; nothing is sent anywhere. You can decline every prompt — Ryvem then boots zero-config on a private local board that works fully offline, and you can edit the .env later.
Choose a board
For Jira you are asked for the base URL (for example https://yourco.atlassian.net) and your Atlassian email before the token. Create the token in the location shown, name it ryvem-mcp, and grant exactly these scopes:
| Board | Where to create the token | Scopes |
|---|---|---|
| Jira | Atlassian account › Security › API tokens › Create API token with scopes (product: Jira) | read:jira-work, write:jira-work, read:jira-user |
| Trello | Trello developer app-key page › copy the Key, then the Token link and Allow | read, write |
| Local board | Nothing to create — a full board lives in the memory graph | — |
Choose a repository host
Then the wizard asks where your repositories live. Provide a token for the one your repo uses (or skip):
| Version control | Where to create the token | Scopes |
|---|---|---|
| GitHub | GitHub › Settings › Developer settings › Fine-grained tokens (select the repositories) | Pull requests: Read and write · Contents: Read |
| Bitbucket | Atlassian account › API tokens › Create API token with scopes (product: Bitbucket — separate from the Jira token) | read:repository:bitbucket, write:repository:bitbucket, read:pullrequest:bitbucket, write:pullrequest:bitbucket |
| GitLab | GitLab › User settings › Access tokens (any host; blank means gitlab.com) |
api |
Bitbucket needs your Atlassian email too
If you did not already give it for Jira, the wizard asks for ATLASSIAN_EMAIL before the Bitbucket token. Jira and Bitbucket use separate Atlassian tokens even though they are created in the same place.
The result is a plain .env next to the binary. You can also write it by hand instead of running the wizard:
ATLASSIAN_EMAIL=you@company.com
JIRA_URL=https://yourco.atlassian.net
JIRA_TOKEN=...
GITHUB_TOKEN=...Already installed? Adding another account
Run ryvem-mcp setup any time to add a second account — a personal board, a second Jira site — as its own named profile, then ryvem-mcp use <name> inside each repo to bind it. The step-by-step recipes are in Configuration.
3. Register with your agent
Ryvem is a stdio MCP server — register the binary with any MCP-capable client. The installer registers Claude Code and Codex automatically when it finds them; otherwise, run the command yourself:
claude mcp add --scope user ryvem -- ~/.local/bin/ryvem-mcpclaude mcp add --scope user ryvem -- "%LOCALAPPDATA%\Programs\ryvem-mcp\ryvem-mcp.exe"For other clients, point a stdio MCP server at the same binary path:
- Cursor / Antigravity — add a stdio MCP server pointing at the binary in the MCP settings (or add
ryvemto~/.cursor/mcp.jsonwithcommandset to the install path). - Codex — add the binary under
[mcp_servers]in the Codex config, or runcodex mcp add ryvem -- <path>.
No MCP prompt support? You lose nothing.
Clients without prompt support get every flow step-by-step from the guide tool, and the harness is driven entirely through harness_next — a single self-describing entry point.
4. First-run smoke check
Open a new terminal (so the updated PATH is picked up) and confirm the binary runs:
ryvem-mcp --versionThen open your agent and run the start-session flow (or call the guide tool). Ryvem lists your boards, learns your stack, and hands you the workflow. That's it — you're ready to work a card end to end.
Something not connecting? Start with doctor
Run ryvem-mcp doctor first. It is a read-only, no-network self-check that prints which credentials it sees (secrets masked), which profile this repo resolves, and any mismatch in plain words — the fastest way to tell a missing token from a mis-bound profile.