mindmap-mcp

Browser mind map + local TypeScript server + MCP.
No Tauri, no Rust, no desktop installer — just Node.js.

中文说明见下方 中文。

---

What you get

URL	Purpose
http://127.0.0.1:17381/	Mind map UI
http://127.0.0.1:17381/mcp	MCP (Streamable HTTP)
http://127.0.0.1:17381/health	Health check

• Multi-session isolation: each browser tab and each MCP connection has its own document by default.
• Agents edit structure via mindmap_apply_op (update_node, insert_child, remove_node, move_node, reorder_children).
• Optimistic concurrency with document_epoch.

---

Quick start (everyone)

Option A — npx (recommended)

Requires Node.js 20+. Opens the UI and starts MCP on port 17381.

npm package: @ewigmidori/mindmap-mcp (org scope; unscoped mindmap-mcp is blocked as too similar to mind-map-mcp).
CLI binary is still mindmap-mcp.

npx @ewigmidori/mindmap-mcp

Or install globally:

npm install -g @ewigmidori/mindmap-mcp
mindmap-mcp

Useful flags / env:

npx @ewigmidori/mindmap-mcp --no-open          # start without opening a browser
npx @ewigmidori/mindmap-mcp --check            # exit 0 if already healthy
npx @ewigmidori/mindmap-mcp --lan              # bind 0.0.0.0 + print LAN URLs (remote machine)
npx @ewigmidori/mindmap-mcp --lan --public-host 192.168.1.20
# MINDMAP_MCP_PORT=17381 MINDMAP_HOST=127.0.0.1 MINDMAP_LAN=1 MINDMAP_NO_OPEN=1

Then wire MCP (or run the write-mcp scripts from a clone) and open a new chat so the client reconnects.

Remote Linux → host browser (LAN)

When the skill/server runs on a remote Linux box (SSH, no display), loopback URLs only work on that box. Use LAN mode so your laptop browser can open the map:

# on the remote machine
npx @ewigmidori/mindmap-mcp --lan --no-open
# or from a git clone:
MINDMAP_LAN=1 ./scripts/ensure-running.sh --lan

Then open the printed LAN UI on your host browser, e.g. http://192.168.1.20:17381/.

Need	How
Force public hostname/IP	--public-host 10.0.0.5 or MINDMAP_PUBLIC_HOST
Full public base URL	MINDMAP_PUBLIC_URL=http://box.local:17381
Discover URLs	GET http://127.0.0.1:17381/health → lan_ui, lan_mcp, ui
MCP on the same remote host	keep http://127.0.0.1:17381/mcp
MCP client on your laptop	use lan_mcp (and open firewall for TCP 17381 on LAN/VPN only)

Headless SSH sessions skip xdg-open and print the host-browser link instead.

Option B — clone & one-shot scripts

git clone https://github.com/EwigMidori/mindmap-mcp.git
cd mindmap-mcp

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File scripts/ensure-running.ps1
powershell -ExecutionPolicy Bypass -File scripts/write-workbuddy-mcp.ps1

macOS / Linux:

chmod +x scripts/ensure-running.sh scripts/write-mcp.sh
./scripts/ensure-running.sh
./scripts/write-mcp.sh

Option C — develop from source

pnpm install   # or: npm install -g pnpm@9 && pnpm install
pnpm build
pnpm start     # same as: node bin/mindmap-mcp.mjs

Wire MCP manually

{
  "mcpServers": {
    "mindmap": { "url": "http://127.0.0.1:17381/mcp" }
  }
}

Client	Config
WorkBuddy	~/.workbuddy/mcp.json
Cursor	~/.cursor/mcp.json
Grok	~/.grok/config.toml → [mcp_servers.mindmap] url = "…" enabled = true

---

Security

• Default bind is 127.0.0.1 only — other machines cannot reach your map.
• --lan / MINDMAP_HOST=0.0.0.0 listens on all interfaces (LAN/VPN). There is no auth on the API — only use on trusted networks, never expose 17381 to the public internet.
• Prefer VPN or private LAN; restrict with host firewall when possible.

---

MCP tools (summary)

Tool	Role
mindmap_list_sessions / mindmap_use_session	Multi-session focus
mindmap_status / mindmap_get_outline / mindmap_get_document	Read
mindmap_apply_op	Tree edit (one op)
mindmap_new / mindmap_open / mindmap_save	Lifecycle

Default MCP session is a private AI document, not the browser tab you are looking at.
To edit the visible tab: list_sessions → use_session → then ops.

Agent skill (for AI operators): skills/mindmap-mcp/SKILL.md.

---

Develop

pnpm install
pnpm dev          # server :17381 + Vite :1420
pnpm build        # UI → dist/ + bundle/server.mjs
pnpm start        # production single process
pnpm typecheck

server/           control plane (REST + WS + MCP) — only write path for agents
src/              React UI
packages/mindmap  domain + canvas
bin/              CLI entry
scripts/          ensure-running / write MCP (Win + Unix)
bundle/           esbuild output (generated by pnpm build)

---

Env

Variable	Default	Meaning
MINDMAP_MCP_PORT	17381	HTTP port
MINDMAP_HOST	127.0.0.1	Bind address (0.0.0.0 for LAN)
MINDMAP_LAN	—	1 = same as bind 0.0.0.0 + advertise LAN URLs
MINDMAP_PUBLIC_HOST	auto	Host printed in UI/MCP URLs (never 0.0.0.0)
MINDMAP_PUBLIC_URL	—	Full public base, e.g. http://box.local:17381
MINDMAP_NO_OPEN	—	1 = do not open browser
MINDMAP_REPO_ROOT	auto	Package root (UI dist/)
MINDMAP_DEV	—	1 = proxy UI to Vite

---

Publishing (maintainers)

npm name: @ewigmidori/mindmap-mcp (public scoped).

Releases use npm Trusted Publishing (OIDC from GitHub Actions) — no long-lived NPM_TOKEN.

1. On npmjs.com → package @ewigmidori/mindmap-mcp → Settings → Trusted Publisher
   • GitHub user: EwigMidori
   • Repository: mindmap-mcp
   • Workflow filename: publish.yml (name only, not the path)
   • Ensure the publisher account can publish under the ewigmidori org
2. Bump version in package.json, push, create a GitHub Release (or run workflow Publish npm manually).
3. Workflow: .github/workflows/publish.yml — id-token: write, npm publish --access public --provenance.

License

MIT © 2026 EwigMidori

---

中文

浏览器思维导图 + 本机 TypeScript 服务 + MCP。 不需要 Tauri / Rust / 桌面安装包，只要 Node。

最快上手（推荐 npx）

npx @ewigmidori/mindmap-mcp

远程 Linux（要在自己电脑浏览器里看）：

npx @ewigmidori/mindmap-mcp --lan --no-open
# 日志 / health 里的 lan_ui → 在宿主浏览器打开

全局安装：

npm install -g @ewigmidori/mindmap-mcp
mindmap-mcp --lan

也可用仓库脚本：

git clone https://github.com/EwigMidori/mindmap-mcp.git
cd mindmap-mcp

• Windows：scripts/ensure-running.ps1 + scripts/write-workbuddy-mcp.ps1
• macOS/Linux：./scripts/ensure-running.sh（远程加 --lan）+ ./scripts/write-mcp.sh
• 开发：pnpm install && pnpm build && pnpm start

默认只监听本机 127.0.0.1；--lan 会监听全网卡，仅限受信局域网/VPN，不要暴露到公网。

对 AI 说「帮我打开思维导图」时，助手应 npx @ewigmidori/mindmap-mcp（远程则加 --lan）并写入 MCP，而不是甩一长串终端命令给你。

MCP 默认连的是独立 AI 会话；要改你正在看的浏览器标签，必须先 mindmap_list_sessions → mindmap_use_session。