nexus-mcp

MCP server exposing the Nexus/TaskBridge PM system to Claude Code, so agents can read and update tasks directly instead of a human relaying state by hand. Paired with two skills in claude-templates — nexus-plan-work (for PM/BA/Team Lead, authoring) and nexus-pick-up-task (for devs, consuming).

Talks to the PM system's public /api/v1/* API — not nexus-vscode's internal endpoints, which are reserved for the official extensions. See DEVLOG.md for why, and for the full build history.

Setup (one time, per person)

Four steps, in order — logging in does not, by itself, make Claude Code aware nexus-mcp exists. That's a separate step (2 below). No git clone needed anywhere in this list — npx fetches, builds, and runs straight from GitHub.

1. Log in — generates a token via the Developer Portal and stores it in your OS keychain (@napi-rs/keyring — never in a file):

export NEXUS_API_URL=http://27.254.62.17:8090
npx -y -p github:tanakorncode/nexus-mcp nexus-mcp-login

Walks you through $NEXUS_API_URL/developer → create an app → grant scopes tasks:read tasks:write projects:read members:read sprints:read → generate a token — then prompts you to paste that token plus your account email.

2. Register with Claude Code — pick one (not both needed, but they can coexist):

• For yourself, every repo, one time (needs the claude CLI — npm install -g @anthropic-ai/claude-code first):

  claude mcp add nexus-mcp -s user -e NEXUS_API_URL=http://27.254.62.17:8090 -- npx -y github:tanakorncode/nexus-mcp

  No .mcp.json needed anywhere after this.

• Or, if a repo you're opening already has .mcp.json committed at its root (e.g. pea-thailand-backoffice-be) — nothing to do, Claude Code picks it up on its own when you open that repo. Only relevant if you didn't do the step above.

3. Reload Claude Code (new window / restart the session) — required either way, the running session doesn't pick up a newly-registered server on its own. First connection is slower (npx fetches + builds fresh); cached after that. Approve the one-time trust prompt.

4. Verify — ask Claude to call whoami. If it resolves your name, all four steps worked.

Install the skills too (once per person — see claude-templates/README.md for details):

mkdir -p ~/.claude/skills
git clone --depth 1 https://github.com/tanakorncode/claude-templates /tmp/claude-templates
cp -r /tmp/claude-templates/skills/nexus-pick-up-task ~/.claude/skills/
cp -r /tmp/claude-templates/skills/nexus-plan-work ~/.claude/skills/

Developing on nexus-mcp itself

If you're changing this repo's own code, not just using it, clone it instead so edits take effect without re-publishing:

git clone https://github.com/tanakorncode/nexus-mcp
cd nexus-mcp
npm install
npm run build
npm link          # makes the `nexus-mcp` command available anywhere on this machine

Point .mcp.json at "command": "nexus-mcp" (no args) instead of the npx form while iterating — rebuild (npm run build) and reload the Claude Code window to pick up changes; the MCP server process holds old code in memory otherwise.

Related MCP server: Dooray MCP Server

The two skills, and when each applies

• nexus-plan-work — breaking a feature into epic/story/task. Use before work exists. The discipline that matters here: one story per feature that spans repos, one task per repo underneath it, repositoryId set on every task (the single most-skipped field, and the one that's unrecoverable later if missed).

• nexus-pick-up-task — finding, understanding, and executing a task, ending in a PR and a status update. Use once work exists and someone (human or a scheduled check) is ready to act on it.

Read the skill files themselves for the full step-by-step — this README won't duplicate them.

Tools

Identity & discovery

Reading tasks

Authoring (see nexus-plan-work)

Hand-off

Optional: scheduled task check (notification only)

scripts/check-my-tasks.sh runs headless (claude -p) and checks list_my_tasks on a timer, firing a macOS notification if anything's ready — it does not start writing code by itself (--allowedTools is locked to read-only tools plus Bash(osascript*), so it structurally can't edit files even if it wanted to).

launchctl load ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist   # enable, runs every 2h
launchctl unload ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist # disable
tail -f ~/Library/Logs/nexus-task-check.log                                     # watch it run
./scripts/check-my-tasks.sh                                                     # run once, right now

The plist itself isn't in this repo (it's local machine config, per person) — copy the one in DEVLOG.md's 2026-08-22 entry, or ask whoever set theirs up.

This only checks; a person still has to open Claude Code and say "go" once notified — see DEVLOG.md if you want the reasoning for why it stops there.

Known limits

• No comment support, no commit-linking — those routes only exist on the extension-only internal API, not /api/v1/*. Would need new pm-system routes to add.

• No epic creation via API — epics are infrequent/lead-planned; use the product UI.

• No attachment/embed upload via API (reading them works — get_task returns both) — attach Figma links/screenshots through the product UI.

• Repo-scoped, story-scoped, and label-filtered queries only return results once someone actually sets repositoryId/storyId/labelIds on tasks — nothing is inferred automatically.