@cpenned/mcp

MCP server for Open Brain. A thin adapter over the /v1 HTTP API: every tool is an authenticated call through the same enforced path as any other API consumer, so the guard layer remains the single write chokepoint.

Configuration

Set via environment variables:

| Variable | Required | Description | | ------------------------ | -------- | ------------------------------------------------------------------ | | OPEN_BRAIN_API_URL | yes | Deployment origin, e.g. https://<deployment>.convex.site | | OPEN_BRAIN_API_KEY | yes | An obr_ API key with the scopes the tools you use require | | OPEN_BRAIN_CLIENT_TYPE | no | X-Client stamped on the audit log (default mcp) |

The key's scopes gate the tools: resource tools need <resource>:read|write, review tools reviews:*, settings tools settings:read|write, and find_tasks / ai_triage need ai:invoke.

Run

The package is published to npm, so the simplest path needs no clone or build - just run it with npx:

OPEN_BRAIN_API_URL=... OPEN_BRAIN_API_KEY=... npx -y @cpenned/mcp

The server speaks MCP over stdio.

Claude Desktop / CLI

{
  "mcpServers": {
    "open-brain": {
      "command": "npx",
      "args": ["-y", "@cpenned/mcp"],
      "env": {
        "OPEN_BRAIN_API_URL": "https://<deployment>.convex.site",
        "OPEN_BRAIN_API_KEY": "obr_..."
      }
    }
  }
}

From source (development)

Building from the monorepo instead of npm:

npm install
npm run build -w @cpenned/mcp
OPEN_BRAIN_API_URL=... OPEN_BRAIN_API_KEY=... node packages/mcp/dist/index.js

Point the args at the absolute packages/mcp/dist/index.js path with "command": "node" if you wire a source build into Claude Desktop.

Tools

• Resources (CRUD, single + batch + multi-get): create_task, list_tasks, get_task, update_task, delete_task, create_tasks, update_tasks, add_task_tags, remove_task_tags; the *_project, *_garden, *_tag equivalents. Task/project deferDate/deadline are calendar days (YYYY-MM-DD); inputs also accept relative tokens like today/+3d.
• People (personal CRM): create_person, list_people (query searches name, aliases, company, notes, and more), get_person, update_person (null clears fields; archived: false restores), delete_person (archives), mark_contacted (optional at backdates), add_person_links/remove_person_links (link people to tasks, projects, gardens, and other people — person-to-person connections are symmetric and take an optional label like "spouse", plus readingListItemIds on either side). People with an elapsed contact cadence appear in get_reviews and ui_review_queue; list_tasks filters by person ids.
• Reading list: create_reading_item (only url is required; title/ description are fetched from the page in the background), list_reading_items, get_reading_item, update_reading_item (drives status unread|reading|read; stamps/clears readAt; archived/deleted toggle independently of status), delete_reading_item (true soft delete, hidden everywhere; restore with {deleted: false}), add_reading_tags/ remove_reading_tags.
• Habits: create_habit, list_habits, get_habit, update_habit, archive_habit, unarchive_habit, complete_habit, remove_habit_completion, reorder_habits, add_habit_tags, and remove_habit_tags. Habits support daily, weekly, monthly, and every-N-days schedules, streak metadata, optional quantity targets, and reversible archive. pausedUntilDay, graceDays, availableFrom, availableUntil, and targetQuantity accept null on update to clear; startDay can be moved but not cleared.
• Strava: list_strava_activities, get_strava_activity, update_strava_activity (notes/archived/deleted only — everything else is Strava-authoritative), delete_strava_activity (soft delete; restore with {deleted: false}), add_strava_activity_tags/ remove_strava_activity_tags, sync_strava_activities (manual backfill/fallback; real-time ingestion is a webhook). No create tool — activities only arrive via webhook or sync. Requires connecting a Strava account first, from the web app's Settings page.
• Calendar (read-only mirror of synced Google Calendar events): list_calendar_events (startMs/endMs epoch-ms window, optional calendarId), list_calendars, sync_calendar. Connect accounts + toggle per-calendar visibility in the web app; link a task to an event with update_task's eventId.
• Books (a personal library, distinct from the reading list above): search_books (q title/author or isbn), create_book (only title required; openLibraryWorkId/isbn schedule background metadata + cover enrichment from Open Library, fill-only-missing), list_books (filter by status[]/format[]/tagIds/personIds/query, or multi-get via ids), get_book (tags, people, linked habit, recent sessions), update_book (drives status want_to_read|reading|read|dnf; null clears a clearable field; habitId: null unlinks the page-goal habit; archived/deleted: false restores), delete_book (soft delete, cover blob kept), add_book_tags/remove_book_tags, log_book_session (retroactive OK, multiple sessions per day, can check off a linked habit for that day - never downgrading a manual completion), remove_book_session, refresh_book_metadata (overwrite?). add_person_links/remove_person_links take bookIds.
• Views & reviews: get_view, get_reviews, review_garden, request_garden_review, mark_task_reviewed, mark_project_reviewed.
• Settings: get_settings, update_settings — the default review period applied to new tasks/projects (2 weeks out of the box; defaultReviewInterval: null disables it, and reviewInterval: null on create_task/create_project opts a single item out). defaultTimezone (IANA string) is also settable - the vault timezone date-only deferDates/ deadlines resolve against. yearlyBookGoal sets the reading-challenge target (books finished this calendar year); null clears it.
• AI: find_tasks (hybrid search), ai_triage (brain-dump triage).
• UI (read-only MCPUI): ui_view, ui_review_queue, ui_garden_board, ui_habits return ui:// HTML resources.
• Key management: create_key, list_keys, rotate_key, revoke_key (require the configured key to hold keys:manage). A key can only grant scopes it itself holds; secrets are returned once. Grant keys:manage deliberately - it lets the agent mint and revoke keys.
• Skills: install_skills copies the bundled open-brain-mcp agent skill into the local skills directory (see below). Purely local; no API call.

Agent skill

The open-brain-mcp agent skill teaches an assistant (e.g. Claude Code) how to use these tools well. It ships inside this package; install it any of three ways:

npx -y @cpenned/mcp install-skills            # into ~/.claude/skills
npx -y @cpenned/mcp install-skills --force    # overwrite an existing copy
npx -y @cpenned/mcp list-skills               # what's bundled
npx -y @cpenned/mcp uninstall-skills

• Let the agent do it: when the server starts and the skill isn't installed yet, the server's instructions ask the connected agent to offer installing it once via the install_skills tool. Say yes and restart the agent.
• Via the CLI package (bundles the CLI skill too): npm i -g @cpenned/cli && ob skills install.
• Or copy .agents/skills/open-brain-mcp from the repo into ~/.claude/skills by hand.

Pass --dir <path> to target a different skills directory. Restart your agent after installing.

Publishing

MIT-licensed and publish-ready (files, publishConfig, prepublishOnly build). To cut a release: bump the version, then npm publish -w @cpenned/mcp from the repo root (@cpenned is the owner's npm username scope, so no org is needed; you must be authenticated as that user). prepublishOnly rebuilds dist first.