mindmap-mcp

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

中文说明见下方 中文。

What you get

• 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.

Related MCP server: Brainstorm MCP Server

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/.

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" }
  }
}

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)

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

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。