Nudge MCP

A Model Context Protocol server that exposes the Nudge board (this repo's Trello-like app) to MCP clients — Claude Desktop, Claude Code, Cursor, anything that speaks MCP over stdio.

It lets an LLM list boards, create cards, assign people, move tasks between columns, drop comments, and read your notifications — using your identity, so mentions and activity logs attribute correctly.

How it authenticates

Nudge's auth is Google-only with an @joygame.com domain restriction, and the JWTs are signed by the Convex deployment itself — there's no key the MCP server could re-sign with from a CLI. So the MCP uses personal access tokens, bootstrapped over a one-shot localhost handshake:

1. Run npx -y @euqns/nudge-mcp setup in a terminal.
2. The CLI opens your browser to Nudge's /mcp-setup page (you'll sign in with Google if you aren't already).
3. Click Authorize. The page generates a token in your name and sends it to the CLI over http://127.0.0.1:<random-port>/callback. The token is never displayed, never typed, never logged.
4. The CLI writes ~/.nudge/credentials at mode 0600 and prints the snippet you paste into your MCP client — that snippet contains no secrets.

Replay protection is via a fresh per-run state nonce; mismatched POSTs are rejected with 403. The listener only binds to 127.0.0.1 and times out after 5 minutes.

You can manage tokens (name, last-used, revoke) from profile → MCP tokens in the web app.

Install

TL;DR

If you already have Node.js ≥ 18 on your machine:

npx -y @euqns/nudge-mcp setup

Then paste the snippet it prints into your MCP client (see Configure). Done.

If node -v errors or prints something older than v18, follow the section for your OS below first.

Step 1 — Install Node.js

npx and npm ship with Node.js, so this is the only prerequisite. Pick one option per OS.

macOS

Option A — nvm (curl, no admin, lets you switch Node versions later):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# close and reopen your terminal (or: source ~/.zshrc)
nvm install --lts

Option B — Homebrew:

# install brew first if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node

Option C — official installer: download the .pkg from https://nodejs.org (LTS), double-click, follow the prompts.

Windows

Option A — winget (built into Windows 10/11, open PowerShell):

winget install OpenJS.NodeJS.LTS

Option B — official installer: download the .msi from https://nodejs.org (LTS) and run it. Leave "Add to PATH" checked.

Option C — nvm-windows (multi-version management): grab the latest nvm-setup.exe from https://github.com/coreybutler/nvm-windows/releases, install, then:

nvm install lts
nvm use lts

After install, close and reopen PowerShell/CMD so node and npx are on PATH.

Linux

Option A — nvm (curl, recommended):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc   # or ~/.zshrc
nvm install --lts

Option B — distro package manager (versions vary, confirm node -v ≥ 18 afterwards):

# Debian / Ubuntu
sudo apt install -y nodejs npm
# Fedora / RHEL
sudo dnf install -y nodejs
# Arch
sudo pacman -S nodejs npm

If apt gives you something older than 18, use NodeSource:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

Step 2 — Verify

node -v    # v18.x or higher
npx -v     # any version number

If either command is "not found", restart your terminal first. On Windows, sign out and back in if PATH still doesn't pick up.

Step 3 — Run setup

npx -y @euqns/nudge-mcp setup

First run downloads the package (~5 seconds, one-time), spins up a localhost listener, and opens your browser to /mcp-setup. Sign in with Google, click Authorize, and the CLI writes ~/.nudge/credentials and prints the JSON snippet for your MCP client.

Corporate / locked-down machines: if npx can't write to its cache or hits a proxy, set npm config set cache "$HOME/.npm-cache" and try again. If your network blocks the public npm registry, you'll need an internal mirror or the standalone-binary route (open an issue).

Local development of this repo

Skip the npm package and run from source:

cd mcp
npm install
npm run build
node dist/index.js setup   # uses the default app URL

Configure

After setup succeeds, copy this into your MCP client. The token lives in ~/.nudge/credentials, so the client config is the same on every machine and contains no secrets:

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nudge": {
      "command": "npx",
      "args": ["-y", "@euqns/nudge-mcp"]
    }
  }
}

Restart Claude Desktop. The Nudge tools appear under the tools menu.

Claude Code

claude mcp add nudge npx -y @euqns/nudge-mcp

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "nudge": {
      "command": "npx",
      "args": ["-y", "@euqns/nudge-mcp"]
    }
  }
}

Overrides

If you need to point at a non-production deployment (PR preview, local dev against convex dev), setup accepts --app-url:

npx -y @euqns/nudge-mcp setup --app-url http://localhost:5173

You can also bypass the credentials file entirely by setting NUDGE_CONVEX_URL and NUDGE_TOKEN in the MCP client's env block — useful for CI or containers.

Tools

| Tool | What it does | |---|---| | whoami | Identity bound to the token (id, email, displayName, team). | | list_boards | Every board the user is a member of. | | get_board | Board layout: lists, labels, members, your role. | | create_board | New board (caller becomes owner, default Backlog/In progress/Review/Done columns). | | list_lists / create_list | Read or add columns. | | list_cards | All cards on a board (subtasks hidden by default). | | my_cards | All cards across all boards where the caller is assigned, soonest due first. | | get_card | One card incl. its description doc. | | create_card | New card in a list (pass parentCardId for subtasks). | | update_card | Patch title/icon/dueDate/assigneeIds/labelIds/priority/listId/description. Pass 'none' to clear dueDate/priority. | | move_card | Drop into another list. Auto-completes if landing in a Done list. | | set_card_completed | Flip the complete bit explicitly. | | delete_card | Hard-delete with cascade (subtasks, comments, activity, notifications). | | create_label | Board-scoped label. | | list_comments / add_comment | Comment threads on a card. @username mentions notify. | | list_members | Board members (use the returned ids for assigneeIds). | | find_user_by_email | Resolve an email to a user id — handy before assigning. | | my_notifications | Recent notifications (assigned / mentioned / commented / moved / updated). |

Boundary notes

• The server runs every call as the user the token belongs to — board access is checked against memberships, the same table the web app reads. There is no "elevated" mode.
• Convex actions run on the same backend as the app, so MCP-driven changes appear in real time in any open browser tab.
• The token is sent as a regular argument over the wire (HTTPS to Convex). Anyone reading the JSON payload would see it, which is why we hash on the server and only ever return the plaintext at creation time.

Development

npm run dev   # tsx watcher — useful with `node --inspect` on the MCP host
npm run build # tsc to dist/

The server doesn't reload tools at runtime; restart the MCP client when you change tool definitions in src/index.ts.