Skip to content

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

After publication
npx @rememo/cli mcp setup
  1. Choose codex, claude or both. The selected client CLIs must be installed before setup can register Rememo.
  2. Use https://app.rememo.io or enter your self-hosted Rememo URL, including any path prefix. An explicit /api/ URL also works.
  3. 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.

After publication
npx @rememo/cli mcp setup --client both --url https://app.rememo.io

Separate 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.

Example · after publication
npx @rememo/cli mcp setup --client codex --url https://tasks.example.com/team --config /ABSOLUTE/PRIVATE/team.json

Standalone 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.

After publication
npx -y @rememo/mcp@0.1.0 --config /ABSOLUTE/PRIVATE/config.json

Configuration 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.

Get started

Create the task from the message that asked for it

We've integrated chat and kanban together so you can create tasks directly from messages.