Fusebase MCP Server

An MCP server that lets AI assistants manage your Fusebase (formerly Nimbus Note) workspaces — pages, folders, tasks, tags, files, members, and more.

Note: Fusebase has no public REST API. This server uses reverse-engineered internal endpoints with cookie-based authentication.

✨ Features

• 63 tools across content, tasks, members, org admin, portals, databases, files, guides, and more

• Two-tier system — 21 core tools load by default; 42 extended tools on demand

• Auto auth retry — detects 401/403 and refreshes session automatically

• Encrypted secrets — cookies stored encrypted at rest (AES-256-GCM)

• Version checking — built-in update detection from GitHub

• API logging — all requests logged for debugging

🚀 Quick Start

Prerequisites

• Node.js 18+

• A Fusebase account

1. Install

Option A — Install from GitHub (recommended):

npm install -g github:ryan-haver/fusebase-mcp

This automatically installs dependencies, compiles TypeScript, and downloads Chromium for auth.

Option B — Clone and build manually:

git clone https://github.com/ryan-haver/fusebase-mcp.git
cd fusebase-mcp
npm install

npm install automatically builds the project and installs Playwright's Chromium via the prepare and postinstall scripts.

2. Configure

Copy .env.example to .env and set your Fusebase details:

cp .env.example .env

FUSEBASE_HOST=yourorg.nimbusweb.me     # Your org's Fusebase hostname
FUSEBASE_ORG_ID=your_org_id            # Found in Fusebase URL or API responses

Where to find these: Log into Fusebase → look at the URL bar. Your hostname is <something>.nimbusweb.me. The org ID appears in API requests (open browser DevTools → Network tab → look for /v2/api/ requests).

3. Authenticate

Run the auth script to capture your session cookies securely:

npx tsx scripts/auth.ts

This opens a browser window → log into Fusebase → cookies are automatically captured and saved encrypted to data/cookie.enc.

Headless mode: After the first login, you can re-authenticate without a browser window:

npx tsx scripts/auth.ts --headless

4. Connect to Your AI Assistant

Add to your MCP client config. Examples:

{
  "fusebase": {
    "command": "node",
    "args": ["/path/to/fusebase-mcp/dist/index.js"],
    "env": {
      "FUSEBASE_HOST": "yourorg.nimbusweb.me",
      "FUSEBASE_ORG_ID": "your_org_id"
    }
  }
}

{
  "mcpServers": {
    "fusebase": {
      "command": "node",
      "args": ["/path/to/fusebase-mcp/dist/index.js"],
      "env": {
        "FUSEBASE_HOST": "yourorg.nimbusweb.me",
        "FUSEBASE_ORG_ID": "your_org_id"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "fusebase": {
        "command": "node",
        "args": ["/path/to/fusebase-mcp/dist/index.js"],
        "env": {
          "FUSEBASE_HOST": "yourorg.nimbusweb.me",
          "FUSEBASE_ORG_ID": "your_org_id"
        }
      }
    }
  }
}

Note: Replace /path/to/fusebase-mcp with the actual path where you cloned the repo. On Windows, use double backslashes: "C:\\path\\to\\fusebase-mcp\\dist\\index.js".

5. Verify

Ask your AI assistant:

"List my Fusebase workspaces"

If it works, you're all set! 🎉

🔧 Tool Tiers

The server uses a core/extended tier system to optimize agent context usage:

Enable extended tools:

• Mid-session: ask your AI to use set_tool_tier with tier: "all"

• Always-on: add FUSEBASE_TOOLS=all to your .env

Core Tools (21)

Extended Tools (42)

Enable with set_tool_tier(tier: "all"):

• Content mutations: delete_page, update_page_content

• Files & attachments: get_page_attachments, list_files, get_file_count, upload_file, download_attachment

• Labels & tags: get_labels, get_note_tags

• Activity & comments: get_activity_stream, get_comment_threads

• Tasks (advanced): get_task_description, get_task_count, get_task_usage

• Organization: get_org_usage, get_org_limits, get_usage_summary, get_org_permissions, get_org_features, get_ai_usage

• Workspaces: get_workspace_detail, get_workspace_emails, get_workspace_info

• Navigation & AI: get_navigation_menu, get_mention_entities, list_agents, get_recently_updated_notes

• Databases: get_database_data, list_databases, get_database_entity, create_database, add_database_row, list_all_databases, get_database_detail, update_database, delete_database, get_dashboard_detail, delete_dashboard, update_view, set_view_representation

• Portals: list_portals, get_portal_pages

🔐 Security

• No plaintext secrets on disk — cookies are encrypted with AES-256-GCM using a machine-scoped key

• Auto-refresh — expired sessions are transparently refreshed via Playwright

• .env is gitignored — credentials never enter version control

• Cookie via env var — optionally pass FUSEBASE_COOKIE in your MCP config for environments where the encrypted store isn't available

🗂️ Project Structure

src/
  index.ts              → MCP server (63 tools, stdio transport, tier system)
  client.ts             → HTTP client (cookie auth, 401 auto-retry, logging)
  crypto.ts             → AES-256-GCM encryption for secrets at rest
  types.ts              → TypeScript interfaces for API responses
  content-schema.ts     → Content block IR (25+ block types)
  markdown-parser.ts    → Markdown → ContentBlock[] converter
  token-builder.ts      → ContentBlock → Y.js token builder
  yjs-ws-writer.ts      → Y.js WebSocket writer (write + read via WS sync)
  yjs-html-decoder.ts   → Y.js document → HTML decoder (20+ block types)
  guide-loader.ts       → Guide search index (231 guides, 17 sections)
scripts/
  auth.ts               → Capture session cookies via Playwright
  scrape-guides.ts      → Scrape FuseBase help guides into markdown + NLM sync
  test-regression.ts    → Comprehensive write→read regression test (20 checks)
  test-guide-tools.ts   → Guide loader integration test (13 checks)
  discover.ts           → Crawl Fusebase UI to discover API endpoints
docs/
  guides/               → 231 FuseBase guides across 17 sections (auto-scraped)
data/                   → (gitignored) Cookie store, API logs, workspace cache

🗺️ Roadmap

See UNIMPLEMENTED_ENDPOINTS.md for 36 discovered but unimplemented API endpoints, prioritized by value:

• Automation — ActivePieces flow/run management (11 endpoints)

• Databases — entity/table CRUD (3 endpoints)

• AI assistant — thread and preference management

🤝 Contributing

1. Fork the repo

2. Create a feature branch

3. Run npm run build to verify TypeScript compiles

4. Submit a PR

📄 License

MIT