开源MCP工具：本地优先markdown笔记

📦 Install

Option A — install script *(recommended, see [Quick start](#-quick-start))*

```sh

⚡ Quick start

One line. No clone, no Bun, no Node — the installer detects your OS + arch, downloads the matching prebuilt binary from the latest GitHub release, drops it in ~/.local/bin (or %USERPROFILE%\.brain.md\bin on Windows), and verifies it runs.

Option B — download the binary manually

Every release ships a single-file executable per platform with the web UI embedded inside it. No Bun runtime, no Node.js, no git clone, no bun install — just download, mark executable, run.

Grab the file for your machine from the latest release: 👉 github.com/mi4uu/brain.md/releases/latest

One-liner — macOS / Linux

```sh

Optional: drop it on your $PATH so you can run `brainmd` anywhere

sudo mv brainmd /usr/local/bin/brainmd brainmd --help # see all flags brainmd --port 4000 # custom port brainmd --vault-dir ~/notes/my-vault # custom vault location

#### One-liner — Windows (PowerShell)

First run: brain.md creates an empty vault at the XDG default ($HOME/.local/share/brain.md/vault on macOS/Linux, the equivalent on Windows) and serves the editor at <http://localhost:3000>. Want to try the demo vault first? Download example/vault/ and pass it with brain --vault-dir ./vault.

Untagged commits also produce binaries — they live as build artifacts on the Actions page with 30-day retention.

Option C — from source

git clone https://github.com/mi4uu/brain.md.git
cd brain.md
bun install
bun run start            # runs the production server on :3000

For development:

bun run dev:server       # backend on :3000
bun run dev:web          # vite on :5173 (with /api proxy)

If you run bun run start from a fresh source checkout (no compiled binary, no web/dist), the server downloads the matching web bundle from the GitHub release into $XDG_CACHE_HOME/brain.md/web/<version>/ on first request and serves from there. To always work offline, run bun --cwd web run build once.

Requires Bun ≥ 1.3. brain.md uses Bun.password (built-in argon2id) so you don't need a native crypto build.

---

🔑 Optional password auth

Default: no auth. Set a password in Settings → Security to switch on bearer-token authentication for both the HTTP API and the MCP endpoints. Password is hashed with argon2id (Bun's built-in Bun.password, no native crypto build needed); tokens live in memory with a 24-hour TTL.

MCP config when auth is enabled

The plain-text MCP example earlier in the README assumes no auth. When you turn auth on, every request to /mcp needs an Authorization: Bearer <token> header. Most MCP clients have a field for it:

Claude Code / Cursor / Continue / any streamable-HTTP client:

{
  "mcpServers": {
    "brain.md": {
      "type": "streamable-http",
      "url": "https://brainmd.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Claude Desktop (stdio-only — needs mcp-remote bridge):

{
  "mcpServers": {
    "brain.md": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://brainmd.example.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

How to get a token. brain.md issues tokens through POST /api/auth/login. You can do it from anywhere — most useful is a quick curl:

curl -X POST https://brainmd.example.com/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"password":"YOUR_PASSWORD"}' | jq -r .token

Paste the returned token into the headers.Authorization field above, restart the MCP client, done.

Heads-up. Tokens have a 24-hour TTL and are stored in memory only — a server restart invalidates every token. If your agent suddenly starts seeing 401 Unauthorized, get a fresh token. Long-term: pin the token on the client and let your agent re-login on 401 (most MCP clients don't do this yet — patches welcome).

If you're embedding the URL itself anywhere persistent, prefer a secret-manager / .env over hard-coding the bearer string.

OAuth 2.1 for Claude.ai web Custom Connectors (v0.4+)

Static bearer tokens are rejected by Claude.ai's Custom Connector spec (MCP authorization spec 2025-11-25 forbids ?token= in the URL and Claude.ai's UI has no field for a static Authorization header). You need full OAuth 2.1 with PKCE and Dynamic Client Registration.

brain.md ships all of it as of v0.4.0. Set a vault password in Settings → Security (this is what gates the consent screen), then in the Claude.ai Custom Connector dialog:

Claude.ai will: 1. Hit GET /.well-known/oauth-protected-resource and discover the embedded authorization server. 2. POST /oauth/register to obtain a client_id (no human input). 3. Redirect you to GET /oauth/authorize?... where brain.md renders the consent page. Type your vault password and click Allow. 4. Redirect back with ?code=..., exchange at /oauth/token with PKCE verifier, get an access token + refresh token. 5. Use the access token for /mcp calls. Tokens are audience-bound (RFC 8707) — a token issued for brain.md cannot be used elsewhere.

Scopes advertised: vault:read, vault:write. Per-folder permissions (set in the web UI) still apply on top — scope grants the surface, folder-perms grant the path. The narrower of the two always wins.

Same flow works with any spec-compliant MCP client: Cursor, ChatGPT Apps, future Anthropic clients, etc. Claude Code / Claude Desktop have shipped before the spec stabilised so they still want a static bearer or the mcp-remote stdio bridge — both documented above.

---

🖥️ The interface

How it compares

brain.md is not trying to replace Obsidian's plugin ecosystem or Notion's databases. It's narrower on purpose: a markdown vault designed from day one as a memory layer for AI agents over the Model Context Protocol.

---