Brains MCP server

Read from the package source without running it. The installed server may list more.

• add_webhook_pattern

  Append a glob or regex pattern to an existing webhook rule's pattern list. Idempotent — adding a pattern that already exists is a no-op.

• append_log

  Append an entry to the wiki log. Use for ingest, query, lint, and error events.

• audit_index

  Diagnose and repair index/storage drift. Reads the Postgres index, checks each entry against the storage backend, and reports ghost rows (in index but not in storage) and unindexed pages (in storage but not in index). Safe read-only by default. Set cleanup=true to delete ghost rows and re-index missing pages. Writes a log entry when cleanup runs. Requires Postgres index to be configured.

• batch_delete_pageswrite action

  Archive-then-delete up to 50 wiki pages in one call. For each page, writes a recoverable archived_pages row before deleting from live storage/index. Set confirm=false (default) for a dry-run manifest. Set confirm=true to execute. Protected system pages are silently skipped.

• create_pagewrite action

  Create a new wiki page with frontmatter and body content. Name is auto-normalized to a wiki-safe .md path. Returns bytesWritten (UTF-8 byte count of the written file). Ingest responsibility rule: if source material contains stable facts, active tasks, and decisions, you MUST split it across taxonomy folders (canonical/, projects/, decisions/) and keep data/ as raw synthesis only.

• create_pageswrite action

  Create multiple pages in one call (fast path for ingest decomposition into canonical/projects/decisions/data). Returns compact timing/count summary by default; set verbose=true for per-page results. Response includes totalBytesWritten (sum of UTF-8 bytes across all created pages) and per-page bytesWritten when verbose=true.

• delete_pagewrite action

  Archive-then-delete a single wiki page. On confirm=true, writes a recoverable archived_pages row (origin path/folder, content, metadata, deleted_by, optional reason) before deleting from live storage/index. Set confirm=false (default) for a dry-run preview. Protected system pages (instructions/brain-routing.md, decisions/readme.md, history/readme.md, log.md, index.md) cannot be deleted.

• export_wiki

  Export wiki pages to a ZIP archive. When outputPath is omitted, builds the ZIP server-side and returns an HTTP downloadUrl (GET it to fetch the ZIP) instead of an inline base64 payload — one export per user per 24h; a repeat call within that window returns the same downloadUrl (reused=true) instead of rebuilding. When outputPath is provided, writes the ZIP to that server path instead (no downloadU

• extract_linkswrite action

  Run link extraction over a filtered set of wiki pages. Inserts/updates rows in the server-side wiki_links graph for pages where the on-write hook missed (e.g. legacy pages, ingest backfill). Requires at least one of tags or folder. Returns { pagesConsidered, pagesProcessed, linksExtracted }. pagesConsidered is every page matching the tags/folder filter; pagesProcessed is the subset that was stale

• generate_claude_instructions

  Refresh the Claude instruction block for an EXISTING Brains-connected project. Returns a markdown block the user can paste into their Claude Project system prompt. For NEW projects, call init_project first — it scaffolds the brain pages and emits the same instruction block.

• generate_gpt_instructions

  Refresh the ChatGPT instruction block for an EXISTING Brains-connected project. Returns a markdown block the user can paste into their ChatGPT system prompt. For NEW projects, call init_project first — it scaffolds the brain pages and emits the same instruction block.

• get_backlinks

  Return the list of pages that link TO the given page (incoming references). Uses the server-side wiki_links graph; pages not yet indexed produce empty results — call extract_links first if needed.

• get_related

  Return pages that share outbound link targets with the given page (second-degree neighbors). Uses the server-side wiki_links graph; pages not yet indexed produce empty results — call extract_links first if needed.

• health_check

  Check server health: storage backend connectivity (Supabase Storage), search index status (Postgres FTS), uptime, and session log status. Call once at session start to confirm the server is reachable before doing work.

• import_brain_source

  Deterministic importer for source brain folders. Supports preview mode (execute=false) and execute mode (execute=true) with folder-based routing and car-profile consolidation.

• import_wiki

  Import a wiki from a ZIP archive. Agent-friendly: pass zipData (a base64-encoded ZIP, e.g. downloaded from export_wiki's downloadUrl and re-encoded) instead of zipPath for fully agent-reachable round-trips. Supports preview (execute=false) and execute (execute=true). Modes: mode='additive' updates/creates ZIP pages without deleting others; mode='replace' mirrors the ZIP exactly (imports all ZIP pa

• init_project

  FIRST CALL for any new Brains setup. Creates the project brain pages (projects/instructions/decisions scaffolding) and returns a ready-to-paste instruction block for Claude or ChatGPT. Idempotent — safe to re-run. To refresh instructions on an already-initialized project, use generate_claude_instructions or generate_gpt_instructions instead.

• list_archived_pages

  List archived_pages rows for the current user (id, original path/folder, deleted_at, deleted_by, reason, restore status). Use this to discover restore candidates.

• list_page_history

  List the version history for a wiki page. Returns snapshots captured before each update_page or patch_page call, newest-first. Use read_page_version to retrieve the content of a specific snapshot.

• list_pages

  List wiki pages with optional filtering by tag or status. PRIMARY routing tool: call list_pages first to get a full inventory. When running with Supabase/Postgres index enabled, this is fast with no file reads; otherwise it falls back to a storage scan. Use the returned names to select candidates, then read_page only those candidates.

• list_webhooks

  List all outbound webhook rules configured for the current user.

• move_page

  Archive (prefix with 'archive-') or rename a wiki page. No hard deletion in v1.

• patch_pagewrite action

  PREFERRED EDIT tool for small/medium changes, and the ONLY edit tool safe on a page too large to read or re-emit in full: {"type": "append"} appends to the raw file server-side and needs no prior read_page and no revision/fileId (GH #632) — it is still subject to the page's byte size cap and will throw PageSizeError if the result exceeds it. Patch a page with surgical edits in one call. Returns by

• pull_session_bundle

  Downloads all relevant wiki pages for your project as a single plain-text bundle (no ZIP decode needed). The returned bundle IS your working set: every listed page is included in full, so do NOT call read_page on any of them afterwards. Work locally in this conversation, then push back with push_session_bundle when done. Measured 10.04s of individual read_page calls versus 3.47s for the same ten p

• purge_wiki

  Permanently delete all wiki pages. Returns a warning and file list when confirm=false. Set confirm=true to proceed. Set exportBeforeDelete=true with exportOutputPath to create a ZIP backup first.

• push_session_bundle

  PREFERRED write-back tool when paired with pull_session_bundle. Two modes: (1) pages mode (recommended) — pass pages=[{name,content,revision?}] for each page you modified; avoids token-limit issues with large bundles. (2) bundle mode (small bundles <20 KB only) — pass bundle string + manifest array. Both modes use the same conflict-strategy semantics. In pages mode, include the 'revision' you got

• read_governance_audit

  Read governance audit log entries (Hive mode only). Returns server-side access filter events for classification review. Only accessible to exec+ users (access_level ≥ 4) when BRAINS_HIVE_MODE=true.

• read_page

  Read a wiki page by filename, returning content, frontmatter, fileId, revision, and outbound_link_count. If you already pulled a session bundle, do NOT call this for any page listed in that bundle — its full content is already in your context; read it from there. Otherwise the REQUIRED retrieval workflow is: (1) list_pages first to get inventory, (2) LLM selects candidate files from results, (3) r

• read_page_version

  Read a specific historical snapshot of a wiki page. Use list_page_history to get the timestamp key, then call this tool to retrieve the full content of that version.

• remove_webhookwrite action

  Permanently delete an outbound webhook rule by ID.

• resolve_project

  Call this FIRST when the user refers to a project, vehicle, property, client or topic by name and you do not already know its brains project slug. Turns freeform context into the project slug plus the path to its instruction file, so you can pull the right project instead of guessing a tag. Returns ranked matches with a confidence and an `ambiguous` flag — when ambiguous is true or confidence is l

• restore_page

  Restore a previously archived page by archiveId or originalPath (+ optional deletedAt). Recreates the page at original path or targetPath, re-indexes it, and stamps restored_at/restored_by on the archive row. Enforces page-limit checks.

• search_pages

  Full-text search across wiki pages. Uses Postgres FTS when Supabase/Postgres index is enabled (fast); falls back to a local scan otherwise. Use for keyword lookups; use list_pages for full inventory and routing.

• set_webhookwrite action

  Create or update an outbound webhook rule. The rule fires a signed POST to the target URL whenever a page matching one of its glob/regex patterns is created or updated. Omit 'id' to create a new rule; pass an existing 'id' to update it. Patterns use glob syntax (e.g. 'projects/brainsapp/open-loop-*.md') or /regex/ syntax.

• stale_pages

  Read-only cold-page report (GH #497 milestone 1): pages in the caller's own wiki last modified before olderThanDays (default 90) with zero search_relevance_signals engagement since that cutoff, sorted coldest-first. Surfaces candidates only — does not archive or delete. Falls back to age-only results with signalsAvailable:false if the signals table is unreachable or Postgres search is not configur

• suggest_links

  Retroactive linking audit: find wiki pages that lack a '## Related pages' section and return ready-to-apply markdown patches suggesting cross-references. Filters by tags or folder. Uses the server-side link graph (shared outbound targets, backlinks) when available; falls back to tag-overlap heuristics. Never writes — patches require explicit review and confirmation before applying with patch_page.

• update_pagewrite action

  FULL REWRITE tool: replaces the page body. Requires fileId and revision from read_page to prevent conflicts — both come from a full read, so this tool cannot be used on a page too large to read or re-emit in one call. Returns bytesWritten (UTF-8 byte count of the written file). Prefer patch_page for targeted edits (use replace_lines when possible); use update_page when intentionally rewriting most

• Code scan206 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitystatic API keys via environment variables6/15
• Maintenancerepository not readable: repo not found3/15
• Maintainer identityno repository or website to verify2/10

Brains: common questions

Is Brains MCP server safe?

With care: it is graded C, so read the findings first (55/100). Read the Brains safety report

How do I install Brains?

It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.

Does Brains need an API key?

Yes. The registry entry asks for GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN, SUPABASE_SERVICE_ROLE_KEY.

Is Brains maintained?

The latest release is v1.85.5.

What can I use instead of Brains?

Servers from other publishers that do the same job: knowmind MCP server, MCP Server and Apify MCP server. Compare all Brains alternatives.