MCP guide
MCP connects Codex or Claude Code to your Rememo tasks. Read context, add updates and act on tasks with your permission.
npm publication is pending. The commands below are for use after publication.
Before you start
- Use Node.js 24.18.1–24.x. Install the Codex or Claude Code CLI you want to connect and make it available on PATH.
- In Rememo, open Settings → Personal → Agent access. Create a personal access token, choose the scopes you need and copy it once.
- Use tasks:read to read tasks, tasks:write to claim or complete them, comments:write to add updates, and context:read for task context. Revoke the token in Agent access when it is no longer needed.
Connect your client
npx @rememo/cli mcp setup- Choose codex, claude or both. The selected client CLIs must be installed before setup can register Rememo.
- Use https://app.rememo.io or enter your self-hosted Rememo URL, including any path prefix. An explicit /api/ URL also works.
- Paste your token into the masked terminal prompt. Setup saves it in a private local file and registers only that file path with the clients. Restart your client after setup.
The default private file is ~/.rememo/mcp/config.json (directory 0700, file 0600 where supported). Keep it private. Do not put tokens in command arguments or shared client settings.
Available tools
rememo_list_tasks- List tasks available to your token.
rememo_get_task- Read a task, its workflow and permitted context.
rememo_claim_task- Claim a task in an explicit destination column when you ask.
rememo_add_task_update- Add a comment to a task.
rememo_complete_task- Complete a task when you explicitly request it.
Your client claims or completes tasks only when you explicitly ask. Claiming needs a concrete destination column. The server does not autonomously claim tasks.
Advanced setup and troubleshooting
Headless setup
Set REMEMO_PERSONAL_ACCESS_TOKEN in your environment, then supply --client and --url. There is no --token argument. Keep the environment value out of shell history and shared logs.
npx @rememo/cli mcp setup --client both --url https://app.rememo.ioSeparate installations
Use --config with a separate absolute private file path for another Rememo installation. Run setup again to update only the Rememo registration; unrelated client settings are preserved.
npx @rememo/cli mcp setup --client codex --url https://tasks.example.com/team --config /ABSOLUTE/PRIVATE/team.jsonStandalone server
For a client you configure yourself, start the stdio server with your private config file. Register the command and file path, never the token.
npx -y @rememo/mcp@0.1.0 --config /ABSOLUTE/PRIVATE/config.jsonConfiguration order: an explicit --config file, then the complete REMEMO_API_URL and REMEMO_PERSONAL_ACCESS_TOKEN environment pair, then the default private file. A partial environment pair is rejected. REMEMO_API_URL is the API base, including /api/.
If connection fails
Check your Node.js version, the selected client command on PATH, the Rememo URL and token scopes. Restart the client after registration. If setup reports a partial registration, fix that client and rerun setup. Revoke and replace an exposed or expired token.