Skip to main content
Glama

hive-mcp

An MCP server for hive — a spatial board for notes, tasks and ideas (an Obsidian-style app where notes live on an infinite canvas).

It lets an AI assistant (Claude Desktop, Claude Code, Codex, Cursor, …) read your board and work on it: create notes and every other node kind, write Markdown, link nodes into mind maps, group them into zones, mark tasks, import files and arrange everything — through the running hive app, so changes appear instantly, follow hive's own rules and can be undone with Ctrl+Z (each tool call is one undo step, labelled MCP: …).

Early beta, made for fun. Expect breaking changes.

Requirements

  • hive 1.7.1 or newer with Settings → AI tools → Allow AI tools (MCP) enabled (on by default).

  • Node.js 20+.

When hive is closed, the read tools still work on the last opened project folder (read-only); writing needs hive running.

Related MCP server: sketchbord-mcp

Install

git clone https://github.com/reteren/hive-mcp.git
cd hive-mcp
npm install   # also builds dist/

Claude Code

claude mcp add hive -- node "C:/path/to/hive-mcp/dist/index.js"

Claude Desktop / other clients (JSON config)

{
  "mcpServers": {
    "hive": {
      "command": "node",
      "args": ["C:/path/to/hive-mcp/dist/index.js"]
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.hive]
command = "node"
args = ["C:/path/to/hive-mcp/dist/index.js"]

Tools

Tool

What it does

get_status

Running?, open project, counts, visible area, selection

describe_node_kinds

Every node kind with its fields and allowed values

list_nodes, get_nodes, search_nodes

Find and read nodes (full Markdown text, links, zone)

read_node_content

What is inside nodes: images/GIFs and inline pictures as real images, text/code files, PDF text, audio/video details with a poster frame, module data, and YouTube links expanded (title, channel, description, thumbnail, transcript)

read_youtube

Any YouTube link: metadata, thumbnail and transcript

view_board

Screenshot of the board (current view or around given nodes)

get_board_overview

Map of the whole project: zones, clusters, kinds, media, tasks

create_nodes

Create any number of nodes of any kind + links in one step, auto-placed without overlaps (row, column, grid, tree)

update_nodes

Rename, edit text precisely (find/replace, append, prepend), move, resize, colours, glow, task, importance, purposes, moods, kind data

delete_nodes, restore_from_trash, list_trash, list_archive

Delete like the Delete key (to Trash) and bring back

move_nodes, arrange_nodes

Exact positions or automatic layouts

list_links, create_links, update_links, delete_links

Lines between nodes

list_zones, create_zone, update_zone, delete_zones

Coloured areas grouping nodes

import_file

Add a file from disk exactly like dropping it on the board

focus_view

Move hive's camera to show nodes

undo_last_change

Undo the last MCP change

save_project

Flush pending saves

Prompts

  • study_project — walks the assistant through the whole project (overview, screenshots, every node's content incl. images, PDFs and YouTube) and asks for a structured summary.

How it works

hive opens a local TCP listener on 127.0.0.1 (random port) protected by a random per-launch token, and writes both to mcp-bridge.json in its config folder (%APPDATA%\dev.hive.app on Windows). This server reads that file, connects, and forwards each tool call to hive, which executes it with the same code the UI uses. Nothing leaves your machine. Turning the setting off closes the listener and deletes the file.

Environment overrides: HIVE_CONFIG_DIR (where to find mcp-bridge.json / last-project.json), HIVE_PROJECT_DIR (project folder for read-only mode).

Development

npm run check   # types
npm test        # unit tests (fake hive bridge, offline reader)
npm run build

License

MIT

Available Tools

25 tools
arrange_nodesArrange nodesA

Lay out existing nodes as a row, column, grid, tree (by their links) or circle starting at origin (default: their current top-left). One undoable step.

Inputs: ids (required), layout (required), gap, origin.

create_nodesCreate nodesA

Create one or many nodes (any kind) and optionally link them, in ONE undoable step (Ctrl+Z in hive removes the whole batch). Nodes get the same defaults as hive's Q menu. Placement: explicit x/y, else near another node, else automatic placement from origin (default: centre of the visible area) using layout, never overlapping existing nodes. Use ref to link nodes created in the same call (e.g. a mind map: layout "tree" + links from the root). Returns the final ids, names and positions.

Inputs: nodes (required), gap, links, layout, +1 more.

create_zoneCreate zoneB

Create a zone either from an explicit rectangle or around a set of nodes with padding. One undoable step.

Inputs: name, rect, color, around.

delete_nodesDelete nodesA
Destructive

Delete nodes exactly like the Delete key in hive: they go to the Trash (restorable with restore_from_trash) together with their links. mode "archive" archives instead. One undoable step.

Inputs: ids (required), mode.

delete_zonesDelete zonesB
Destructive

Delete zones; their nodes stay on the board. One undoable step.

Inputs: ids (required).

describe_node_kindsNode kinds and fieldsA
Read-onlyIdempotent

Every node kind hive supports (note, beacon, list, tierlist, goal, calendar, …) with a description, default width, whether it has a Markdown body, and its kind-specific data fields; plus the allowed values for importance, purposes, moods, link kinds and shapes, and the Markdown syntax hive renders. Call before creating anything other than plain notes. Needs hive running.

Inputs: no named parameters.

focus_viewShow on screenA
Read-onlyIdempotent

Move hive's camera so the given nodes (or rectangle) are visible — use after creating something so the user sees it. Not an undo step.

Inputs: ids, bbox, zoom.

get_nodesGet nodesA
Read-onlyIdempotent

Full data of up to 50 nodes by id or exact name: every stored field, the complete Markdown text, effective size, links (with the other node's name) and zone.

Inputs: ids, names.

get_statushive statusA
Read-onlyIdempotent

Start here. Returns whether hive is running, the open project (name, folder), object counts, the camera and the visible board area (board units) and the current selection. When hive is closed the result has offline:true and only read tools work.

Inputs: no named parameters.

import_fileImport fileA

Add a file from disk to the project exactly like dropping it on the board: it is copied into the project folder (big videos above the user's threshold are linked instead) and becomes an image, GIF, PDF, audio, video, text/code (format) or source node. Use an absolute path.

Inputs: path (required), x, y, name, +1 more.

list_archiveList archiveC
Read-onlyIdempotent

Archived nodes of the project.

Inputs: no named parameters.

list_nodesList nodesA
Read-onlyIdempotent

List nodes with filters (kind, zone, task state, text query, rectangle, linked to a node) and paging. Returns short summaries with a 160-character text preview; use get_nodes for full text. Coordinates are board units, x/y = top-left, y grows downward.

Inputs: bbox, sort, task, limit, +5 more.

list_trashList trashA
Read-onlyIdempotent

Entries in the project's Trash (deleted nodes) that restore_from_trash can bring back.

Inputs: no named parameters.

list_zonesList zonesA
Read-onlyIdempotent

Zones (coloured areas that group nodes) with their rectangles and member node ids.

Inputs: no named parameters.

move_nodesMove nodesA

Set exact top-left positions (board units) of nodes. One undoable step.

Inputs: moves (required).

restore_from_trashRestore from trashA

Restore Trash entries by id (as listed by list_trash) to their old place, with their links. One undoable step.

Inputs: ids (required).

save_projectSave nowA
Idempotent

Write all pending changes to the project folder immediately (hive also saves automatically).

Inputs: no named parameters.

search_nodesSearchA
Read-onlyIdempotent

Search node names, kinds and text with hive's own Search ranking (name matches first). Returns ids, names and a snippet around the match.

Inputs: query (required), limit, types.

undo_last_changeUndoA
Destructive

Undo the most recent change in hive. By default only undoes changes made through this MCP server (entries labelled "MCP: …") and refuses if the user changed something since.

Inputs: onlyIfMcp.

update_nodesUpdate nodesA

Change existing nodes in ONE undoable step: rename, replace or precisely edit the Markdown text (find/replace that must match exactly once, append, prepend), move/resize, colours, glow, header, task state, importance, purposes, moods, zone, kind-specific data. Only the fields you pass change.

Inputs: updates (required).

update_zoneUpdate zoneA

Rename, recolour or move/resize a zone. One undoable step.

Inputs: id (required), name, rect, color.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target clearly distinct resource+action pairs (create/update/delete/move/arrange nodes, CRUD for links and zones, trash/archive handling). A few boundaries blur: move_nodes vs arrange_nodes vs update_nodes (which also moves/resizes), and search_nodes vs list_nodes (which takes a text query) vs get_nodes, though descriptions clarify the intended use.

    Naming Consistency4/5

    Almost all tools follow a clean snake_case verb_noun pattern (create_nodes, list_links, update_zone, delete_links). The main blemish is pluralization drift within the same resource (create_zone singular vs list_zones/delete_zones plural) and describe_node_kinds, but overall it is predictable and readable.

    Tool Count3/5

    25 tools is at the heavy end for the apparent scope. The domain (nodes, links, zones, trash, archive, files, view, project) is genuinely rich and most tools earn their place, but full CRUD replicated across nodes/links/zones plus many utility verbs makes the surface feel crowded and could be consolidated.

    Completeness4/5

    Coverage is strong: full CRUD across nodes, links, and zones, plus trash listing/restore, import, view focus, undo, save, status, kind introspection, and list/get/search. The one notable dead end is archive handling — list_archive exists but there is no restore/unarchive operation, and no permanent delete or empty-trash.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to read, write, and search local tldraw (.tldr) files, providing a persistent visual scratchpad for diagramming and note organization. It supports full CRUD operations on canvas shapes and metadata management for local canvas files.
      18 npm
      3
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI models and browser users to collaboratively create and edit a shared freeform canvas of positioned cards and directed connections, with tools for adding, updating, linking, and exporting boards as JSON or SVG.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Lets AI tools create and edit Excalidraw diagrams in a CanvasKeep workspace: generate diagrams from nodes and edges with auto-layout, organize them into workspaces and folders, and read or save full scenes.
      12
      64 npm
      MIT