Connect with Claude & LLMs (MCP)

@peoplenexteam/toodoori-mcp is an MCP (Model Context Protocol) server that lets LLMs like Claude manage your toodoori tasks directly. It’s a thin stdio server wrapping the toodoori API, authenticated with a Personal Access Token (PAT) so it passes through toodoori’s existing auth and permission checks.

Once connected, you can tell Claude things like:

“Show me tasks due this week”, “Create a ‘request review’ task in this project”, “Move my finished tasks to Done.”

What you’ll need

1. A toodoori account and a Personal Access Token (PAT)
2. An MCP-capable client — Claude Desktop or Claude Code
3. Node.js (to run via npx)

Step 1 — Generate a Personal Access Token (PAT)

The MCP server calls the API on your behalf using a PAT.

1. Sign in at toodoori.com.
2. Go to My Page → Access Tokens.
3. Click Generate token, give it a name, select only the scopes you need, and choose an expiration.
4. Copy the generated token (tdr_pat_...).

⚠️ The token is shown only once right after creation. Store it somewhere safe (a secret manager). You won’t be able to see it again.

Least privilege: if you only need read access, select read scopes only. Enable a resource’s write scope only when you need to create or modify tasks.

Step 2 — Add it to Claude

Register it once for whichever tool you use.

Claude Desktop (easiest)

Paste the following into claude_desktop_config.json and replace only tdr_pat_... with your token from Step 1 (leave the address as is).

{
  "mcpServers": {
    "toodoori": {
      "command": "npx",
      "args": ["-y", "@peoplenexteam/toodoori-mcp"],
      "env": {
        "TOODOORI_PAT": "tdr_pat_...",
        "TOODOORI_API_BASE": "https://api.toodoori.com"
      }
    }
  }
}

Save and restart Claude Desktop — the toodoori tools will appear.

This config file lives in your personal home folder (~/Library/Application Support/Claude/), so it is not part of any code repository (no git-push risk). The token is stored in plaintext there, so grant only the scopes you need, keep expirations short, and revoke it if you suspect a leak.

Claude Code (terminal users)

⚠️ Putting the token directly in claude mcp add makes the server work only in that project, and the token ends up in a file that can be accidentally committed to git. Instead, ① keep the token in a shell environment variable and ② register it at user scope (--scope user) — then it works in every project and the token is never written into any config file.

① Add the token to your shell profile (~/.zshrc or ~/.bashrc):

export TOODOORI_PAT="tdr_pat_..."
export TOODOORI_API_BASE="https://api.toodoori.com"

Then open a new terminal or run source ~/.zshrc.

② Register at user scope (no token in the command):

claude mcp add --scope user toodoori -- npx -y @peoplenexteam/toodoori-mcp

The registration is stored in your home directory (~/.claude.json) and contains no token — the MCP server inherits the environment variables above at launch. (Run claude from a terminal where those variables are set.)

Sharing with a team: don’t register with the token via --scope project (which writes .mcp.json into the repo). If you need to share, commit a token-free config and have each member set the token via their own shell environment. Add .mcp.json and .env to .gitignore.

What can it do?

The server exposes 24 tools.

• Read: list projects, boards, and stages; search tasks (global or per-project); get task details; list labels and sub-projects; read attachments
• Task management: create, update, move (single/bulk), archive, and delete tasks; change labels; add and update checklist items; write notes; upload attachments
• Configuration: create labels, update sub-projects

It operates only within the scopes you granted. For example, a token with only tasks:read can view tasks but will be denied (403) when trying to create or modify them.

Conventions worth knowing

• A due date is represented as expectedEnd.
• Task content, retrospectives, and notes are exchanged as markdown strings.
• Project / sub-project IDs are encoded strings — don’t fabricate them; use the id returned by the list tools as-is.
• Errors are returned as { error, code, status }, so the LLM can self-correct based on code.

Security notes

• The PAT is header-only. Never expose it in URLs or commit it to a repository.
• Grant the minimum scopes needed and keep expirations short.
• If a token leaks, immediately revoke it — or rotate it (issues a new token and revokes the old one instantly) — from My Page → Access Tokens.

Next steps

With the integration in place, hand tasks to Claude in plain language. The daily tidying, moving, and creating you used to do by hand becomes a single sentence — and your board stays up to date.