Second Brain Bridge

io.github.IsaiahDupreePublished by GitHub account IsaiahDupreev1.3.0Updated Oct 24, 2026

Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.

The publisher's own server: BrainDog

VerifiedStreamable HTTPWeb executableFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Connects ChatGPT to an Obsidian-style Markdown vault on your own Mac so it can search, read and answer questions grounded in your notes.

What you can do
  • Search the vault by keyword and get ranked passages
  • Ask questions answered from your own notes
  • Read a full note by title or id, and list the folders or sources in the vault
  • Show the notes that link to a note through wikilinks (Pro)
  • Create a new Markdown note in the vault (Pro)
  • Show the current plan and upgrade link
When to use it
Useful if you keep notes as a Markdown vault on a Mac and want ChatGPT to retrieve and reason over them without uploading the vault to a third-party knowledge base. Best for personal research, decision recall and drafting new notes from chat.
Requirements
A remote MCP endpoint with OAuth sign-in, plus a free account and a pairing code. A local Node-based agent (Node 18+, Node 22.13+ for the private index) must be installed on the Mac, kept running, and pointed at the vault folder via SECONDBRAIN_VAULT or the agent config file. The Mac must be awake and the agent online; macOS may ask once for Files-and-Folders access.
Before you install
Notes pass through a hosted relay in short-lived job queues, so note content leaves the Mac in transit even though reads and writes happen locally. The agent token and vault path are stored in a local config file. Creating notes writes to your vault and is marked destructive so the assistant should confirm first. Pro features and unlimited searches require a paid Stripe subscription; the free tier is capped at 20 searches per day. Self-hosting needs Supabase and Stripe credentials.

Installation

In SourceWeft

  1. Open Second Brain Bridge in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.IsaiahDupree%2Fsecond-brain-bridge/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "second-brain-bridge": {
      "type": "http",
      "url": "https://secondbrainbridge.vercel.app/mcp"
    }
  }
}

README

🧠 SecondBrainBridge

Your Obsidian vault, searchable and reasoned over — inside ChatGPT, from your own Mac.

[License: MIT] [npm]

SecondBrainBridge is a Model Context Protocol (MCP) connector that lets ChatGPT search and reason over your Obsidian-style Markdown vault — a folder of notes on your Mac. Reads execute locally and requested results pass through the authenticated relay — every action runs on your own Mac through a tiny local agent. The cloud piece is only a stateless relay that shuttles requests between ChatGPT and your Mac.

  ChatGPT  ──OAuth──►  SecondBrainBridge relay  ──job queue──►  second-brain-agent  ──►  Obsidian vault (connector)          (Vercel, stateless)      (your Mac, polls & executes)      (Markdown notes on your Mac)

Your Mac is the only place your notes are ever read or written. The relay stores only short-lived job payloads and your account record; it never sees note content unless a job is in flight, and jobs expire in seconds.

For users — 3 steps

1. Create your account at secondbrainbridge.vercel.app and generate a pairing code.

2. Install the Mac agent (needs Node 18+):

bash
npx second-brain-agent pair <YOUR-CODE>   # link this Mac to your accountnpx second-brain-agent install            # keep it running on every restart

Point it at your vault folder — set SECONDBRAIN_VAULT=/path/to/your/vault, or save the path in ~/.secondbrainbridge-agent.json. The first time the agent reads a vault kept in a protected location (Documents, Desktop, or iCloud Drive), macOS asks once for Files-and-Folders access — click OK.

3. Connect ChatGPT: Settings → Plugins → turn on Developer mode (Security & login) → Create a custom plugin → paste the MCP Server URL https://secondbrainbridge.vercel.app/mcp → Authentication OAuth → sign in & Allow.

That's it. In a new chat: "Search my notes for the Q3 planning doc" or "What did I decide about Project Atlas?"

Your Mac must be awake with the agent running. npx second-brain-agent install makes it start automatically at login and restart if it ever crashes.

Managing the agent

bash
npx second-brain-agent status      # is it paired & reachable?npx second-brain-agent logs        # recent activitynpx second-brain-agent uninstall   # stop auto-start

What ChatGPT can do

ToolActionPlan
search_knowledgeSearch your vault by keyword; returns ranked passagesFree
askAsk a question and get an answer grounded in your own notesFree
get_noteRead one full note by title or idFree
list_sourcesList the folders/sources in your vaultFree
backlinksShow the notes that link to a note (the [[wikilinks]] graph)Pro
create_noteCreate a new Markdown note in your vaultPro
get_planShow your current plan and an upgrade linkFree

Retrieval is v1 ranked keyword + title match, so answers stay grounded in the passages that actually appear in your notes. (Semantic/cloud ranking is a Pro/cloud enhancement.)

Plans

SecondBrainBridge is free to start. Upgrade to Pro when you want the full graph and write access.

FreePro — $8/mo
Search, ask, and read your notes✓✓
List folders/sources✓✓
Searches per day20 / dayUnlimited
Backlinks / [[wikilinks]] graph—✓
Create notes from chat—✓
Cloud aggregation across Macs—coming soon

Billing is handled by Stripe. Upgrade at secondbrainbridge.vercel.app/upgrade, and run get_plan in any chat to see your current plan plus an upgrade link. The relay enforces the Free daily cap and gates the Pro tools by your Stripe subscription (test mode for now).

Self-hosting

You can run your own relay so nothing depends on the hosted instance.

Prereqs: a Vercel account and a Supabase project (free tiers are fine).

  1. Storage — in your Supabase project's SQL editor, run supabase/schema.sql. It creates a tiny Redis-shaped KV + queue surface (nb_* functions) with RLS on.
  2. Deploy the server/ directory to Vercel.
  3. Set env vars (see server/.env.example):
    • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY — your project + service-role key
    • JWT_SECRET — openssl rand -hex 32
    • STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET — for the Pro tier (optional; Free-only if omitted)
  4. Verify: curl https://YOUR-APP.vercel.app/api/health → redisConfigured, redisOk, jwtSecretSet all true.
  5. Point the agent at it: npx second-brain-agent pair <CODE> --server https://YOUR-APP.vercel.app.

How it works

  • Auth — OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). ChatGPT registers itself, the user signs in on the SecondBrainBridge consent page, and ChatGPT gets a scoped MCP access token. JWTs are HMAC-signed; three kinds (session, agent, mcp) with distinct privileges. Optional email verification via Resend (RESEND_API_KEY); off unless configured, and enforcement is opt-in (REQUIRE_EMAIL_VERIFICATION).
  • Relay — MCP tool call → job pushed to jobs:<user> (TTL ≤ the caller's wait window, so an abandoned job can't run late) → the Mac agent (holding a hanging long-poll) is handed the job within ~200ms, executes it, pushes the result → the MCP handler returns it. The long-poll means jobs are delivered on arrival rather than on a fixed interval, so relay overhead is ~300ms instead of ~1s. The agent is considered "online" only while it's actively connected. The relay also enforces the Free daily search cap and unlocks the Pro tools based on the account's Stripe subscription.
  • Agent — a dependency-free Node CLI. It indexes the Markdown files in your vault folder and answers retrieval queries locally (ranked keyword + title match); create_note writes a new Markdown file into the vault. Reads and writes happen straight against the filesystem — the first touch of a protected folder triggers the one-time macOS Files-and-Folders prompt. A macOS LaunchAgent keeps it alive across logins and crashes.

Repository layout

server/    Vercel functions: OAuth + MCP endpoint + relay + Stripe billing   (deploy this)agent/     second-brain-agent — the npm-published Mac CLI that indexes your vault  (users npx this)kit/       Browser automations: register the dev-mode connector AND           fill the OpenAI directory submission (see kit/README.md)supabase/  schema.sql for self-hosting the storagetest/      end-to-end OAuth + MCP integration test

Development

bash
# servercd server && cp .env.example .env.local   # fill in, then: vercel dev# end-to-end test against a live deployment (reads ../.env.local)node test/e2e-oauth.mjs# agent unit testsnode --test agent/test-agent-unit.mjs

Security & privacy

  • Notes are read/written only on your Mac. The relay temporarily stores requested content in short-lived job/result queues — job payloads live in Redis-shaped storage with a short TTL and are deleted on delivery.
  • The agent token (and your vault path) is stored at ~/.secondbrainbridge-agent.json (mode 600); the vault path can also come from SECONDBRAIN_VAULT.
  • No secrets are committed; see .gitignore and the .env.example files.
  • The write tool (create_note) is marked destructive so ChatGPT asks before adding a note.

License

MIT © Isaiah Dupree

Production storage and owner verification

Relay 1.4 uses isolated service-role-only tables/functions on the configured shared Supabase project. Production refuses missing storage configuration, bounds RPC requests to ten seconds, and returns HTTP 503 when storage or signing configuration is unavailable. Apply the checked-in isolated-storage migration before deploying this version; it does not replace another bridge's account tables or functions.

node --env-file=.env.local test/live-storage.mjs verifies the actual persistent store, FIFO, expiry and counters using temporary integration keys. BRIDGE_SESSION_FILE=/private/owner-session.json BRIDGE_READ_TOOL=READ_TOOL node test/live-relay.mjs verifies the actual owner session, PKCE OAuth, hosted MCP and paired-Mac read; choose this bridge's inventory tool. No reviewer data counts as a live acceptance. Credentials and sessions belong outside Git.

Private vault index (source agent 1.1)

Requires Node 22.13+. Set the exact vault in the agent config, then run node agent/cli.mjs index-install. This builds a private SQLite snapshot under ~/Library/Application Support/SecondBrainBridge/ and incrementally checks changes every 15 minutes. It indexes Markdown/text files, excludes dot directories and symlinks, and reports the complete count without a silent 5,000-file cap. Search/list responses include the snapshot time and 15-minute freshness boundary. Fetch reads current file text; creating a note refuses overwrites and invalidates the snapshot. No embedding/model service is started.

node agent/cli.mjs index-status reports counts and freshness. node test/live-index.mjs checks actual ID coverage, private permissions, live text comparisons and read/search results. uninstall removes the refresh job while retaining the private index. No npm publication is claimed for this source upgrade.

Source: README.md at commit fe4df53

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v1.3.0LatestSep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Brain integrations

BrainDog

dog.brainOfficial publisher

BrainDog is a hosted record of projects, decisions and money that connected AI agents read before starting work and write their results into.

Streamable HTTPWeb executableAuth
FinanceCredential requiredNov 5, 2026

Codebase Brain

Published by GitHub account Nomannazir

Indexes a local or public git codebase so an assistant can search it, trace git history, check change impact and find stale docs, all with path:line citations.

STDIODesktop only
Developer ToolsNot validated yetNov 7, 2026

Personal Brain

Published by GitHub account zhang-liz

Gives an AI assistant memory of your professional network, stored as a graph in FalkorDB, so it can look up contacts, find people by topic, and save who you…

STDIODesktop only
Databases3 toolsNov 6, 2026

Second Brain

Published by GitHub account ara-5

Shared Graph-RAG memory for AI agents: markdown vault, wikilink recall, tasks, messaging.

STDIODesktop only
AI & ML12 toolsNov 7, 2026

Make0 Brain

Published by GitHub account make0-official

Local, offline memory server that gives Claude Code, Cursor, Codex and other MCP agents one shared, versioned store of durable facts.

STDIODesktop only
AI & MLNot validated yetNov 7, 2026