noeto-mcp

An MCP server that lets an AI agent work a noeto kanban board: read it, create and update cards, move them, comment, and keep a written document on a card.

Quick start (Claude Code)

1. In noeto, Settings → Access tokens → Create token, and copy the secret.

2. Install the plugin. It bundles the server and the /card workflow:

   sh

   /plugin marketplace add noeto-tasks/noeto-mcp
   /plugin install noeto@noeto-mcp
   

3. Export the token and restart Claude Code:

   sh

   export NOETO_TOKEN=noeto_pat_…
   export NOETO_API_URL=https://api.noeto.online/api/v1
   

Then ask: "What's on my board?" More in the plugin README.

Other ways to run it

Docker, for any MCP host:

claude mcp add noeto -s user \
  -e NOETO_TOKEN=noeto_pat_… \
  -e NOETO_API_URL=https://api.noeto.online/api/v1 \
  -- docker run -i --rm -e NOETO_TOKEN -e NOETO_API_URL ghcr.io/noeto-tasks/noeto-mcp:v0.6.5

Or by hand in ~/.claude.json, .mcp.json or Claude Desktop's config:

{
  "mcpServers": {
    "noeto": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NOETO_TOKEN", "-e", "NOETO_API_URL",
               "ghcr.io/noeto-tasks/noeto-mcp:v0.6.5"],
      "env": {
        "NOETO_TOKEN": "noeto_pat_…",
        "NOETO_API_URL": "https://api.noeto.online/api/v1"
      }
    }
  }
}

Native binary, with Homebrew:

brew install noeto-tasks/tap/noeto-mcp
claude mcp add noeto -s user \
  -e NOETO_TOKEN=noeto_pat_… \
  -e NOETO_API_URL=https://api.noeto.online/api/v1 \
  -- "$(brew --prefix)/bin/noeto-mcp"

Or take an archive from releases (macOS, Linux, Windows). The binary is unsigned, so on macOS run xattr -d com.apple.quarantine noeto-mcp first. Point the config at it by absolute path.

Good to know

• One server serves one team — the token decides which. For two teams, add two entries with their own tokens (noeto-work, noeto-personal).
• Against a local noeto from Docker, use http://host.docker.internal:8081/api/v1 (macOS, Windows) or --network host (Linux).
• It runs as a local process, so it works in Claude Code and Claude Desktop, not in claude.ai in the browser or the mobile apps.

Tools

• Boards, columns, labels and people can be named: move_card(card, column: "Done"). The card itself needs its id, so a typo can never edit the wrong card.
• none clears a field: update_card(card, due: "none"). An omitted argument leaves it alone.
• Documents and text files are capped at 512 KB, images at 1.5 MB. Bigger files and other types go through download_attachment.
• Downloads land in NOETO_DOWNLOAD_DIR (default: noeto-attachments in the system temp directory). In Docker, mount that directory at the same path on both sides — the plugin's config already does.

It deliberately cannot delete anything a person made, and does not create boards, columns or labels. The reasoning behind these and the other choices is in docs/internals.md.

Development

make test         # hermetic, against a fake API
make smoke        # contract check against a running noeto (needs NOETO_TOKEN)
make lint
make docker       # build the image for this machine
make release-dry  # build release artifacts into dist/, publish nothing

Run make smoke after any API change.

Releasing: Actions → Release → Run workflow, with the version (0.6.3). It tests, pins the version, pushes the image, tags, publishes the GitHub release and Homebrew cask, and lists the version in the MCP Registry. It needs a HOMEBREW_TAP_TOKEN secret that can write to noeto-tasks/homebrew-tap. make release-plugin RELEASE=x.y.z does the same from a laptop, except the registry: run the Publish to MCP Registry workflow afterwards.