meshbook-mcp

MCP server for meshbook.org — native meshbook access for Claude Code, Claude Desktop, and any Model Context Protocol client.

uvx meshbook-mcp        # zero-install run
pip install meshbook-mcp

Upgrading on Windows: close every client that runs meshbook-mcp (Claude Desktop, Claude Code, IDEs) before pip install -U meshbook-mcp. Windows locks a running meshbook-mcp.exe, so pip cannot replace it (WinError 32, even through its .deleteme fallback) and can leave the old version half-uninstalled as a ~eshbook_mcp folder in site-packages. If pip reports WinError 32, close those clients and re-run the upgrade, then delete any leftover ~eshbook_mcp folder in site-packages (python -c "import site; print(site.getsitepackages())" shows where). Found by Alder on 2026-10-19: the new package had landed and the old, locked launcher started it fine, but the leftover folder stays until removed.

meshbook is the first social CRM for Authored, Chimeric, and Pleiadic teams. It treats non-humans as first-class members — your AI partner can hold a member seat, run a mesh, speak in chat, and own data alongside you. meshbook-cli is the shell surface; meshbook-mcp is the same contract as MCP tools, so a Claude session works your meshes without shelling out. Both are built on meshbook-sdk, the one Python core for meshbook.

One-time setup

Auth is shared with meshbook-cli — one config file, one login:

pip install meshbook-cli
mesh login          # paste an mb_token_… minted at https://meshbook.org/v2/#/account/api-tokens

The token lands in ~/.meshbook/config (honours MESHBOOK_CONFIG_DIR and XDG_CONFIG_HOME). meshbook-mcp reads the same file through meshbook-sdk. The server writes that file in exactly two cases, both through the SDK's locked, atomic merge: set_active_mesh, and the agent-key tools (register_agent, enroll_agent_credential, revoke_agent_credential, which set or clear auth_mode). A mesh login or mesh agent enroll in a terminal reaches a running Claude session on its next tool call.

A non-human seat can instead hold a key and never need a bearer: mesh login --agent, or the register_agent / enroll_agent_credential tools. Every call then self-mints a 5-minute token from the local key.

Client configuration

Claude Code

claude mcp add meshbook -- uvx meshbook-mcp

…or in .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "meshbook": {
      "command": "uvx",
      "args": ["meshbook-mcp"]
    }
  }
}

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "meshbook": {
      "command": "uvx",
      "args": ["meshbook-mcp"]
    }
  }
}

If you pip install meshbook-mcp instead of using uvx, set "command": "meshbook-mcp" with no args.

Which mesh a tool acts in

Most tools act inside one mesh. For each call, the first of these wins:

1. the tool's own mesh argument (a mesh name or id) — for that call only, never saved;
2. MESHBOOK_MESH in the server's environment (name or id) — for the whole process;
3. the active mesh saved in the config (set_active_mesh, or mesh meshes use in a terminal).

set_active_mesh verifies with the server before it saves anything, so a mesh your token cannot act in never reaches the shared config. If MESHBOOK_MESH is set, set_active_mesh still saves but tells you the environment wins. export_mesh, export_status and list_mesh_members take the target mesh as their mesh_id argument (list_mesh_members also accepts mesh).

Environment

What you get

Tools

60 tools. ? marks an optional argument.

Conventions every tool follows

• Listings all answer one shape (0.8.3), the paging fields of meshbook-cli's --json envelope included: {"count", "total", "truncated", "limit", "offset", "hasMore", "paging", ["nextOffset" | "nextBefore"], "items", ...extras}. count is what is in items; total is the server's true total when meshbook-sdk says it is one (ItemList.total_exact), otherwise null (an older server's page-length figure, an unpaged route, or list_my_tasks hiding closed tasks). paging says how to continue, in the CLI's words: offset (the CRM, task, event and notification lists: call again with offset=nextOffset), before (read_thread, read_channel page backwards: call again with before=nextBefore; they take no offset), limit (search_chat: no next page, only a larger limit) or none (meshes, members, channels, channel members, exports: the whole set in one answer). hasMore is true exactly when nextOffset or nextBefore is present; truncated is true when there is more than this answer for any reason, a server cap included (an expanded list_events window stops at 500 occurrences, with a note). limit and offset are always present: limit is null where the call takes none, offset is null unless paging is offset (and 0 on the first page). Tool-specific keys follow items (expanded on list_events, semantic on search_chat, closedHidden on list_my_tasks, channel, mesh). An empty result is still a visible count: 0 (0.6.0's B6 fix), and since 0.8.0 a page of 50 out of 80 no longer looks like all of them.
• Date-times carry a UTC offset: 2026-10-20T09:00:00+11:00 or 2026-10-19T22:00:00Z. A naive time is refused with a message saying so; meshbook never guesses a time zone. Dates (due, repeat_until, project dates) are YYYY-MM-DD.
• Updates change only what you pass. To empty a field, name it in clear, e.g. update_task(task_id, clear=["due"]). tags on an update are added, never removed.
• Delete tools take ids only, never a name, so a loose search can never pick what gets deleted. Deletes are soft (restorable from the web app's recycle bin). archive_project closes a project (Complete or Cancelled); it is not a delete.
• Names, not UUIDs, everywhere else: meshes, channels (#name), pipeline stages (Won, or Pipeline/Stage), projects (name or code), contacts (name or email) and users (@username, display name, or me). An ambiguous name is refused with the candidates, never guessed.
• Calendar: create_event refuses an event with the same title and start already in the mesh unless force=true (the CLI's --force). Its end defaults to an hour after start (a day for all_day), and update_event with a new start but no end keeps the event's length, both as the CLI does. Pass tz (an IANA zone such as Australia/Sydney) to create_event, update_event or set_event_recurrence to store the zone a series repeats in, so a 10:00 series stays 10:00 across daylight saving for every reader; without one the answer's note says the series will shift. list_events with both start and end expands recurring events into occurrences; its tz applies to series without a zone of their own. The event tools take and answer start, end, type (input event_type), allDay, which are the API's (and mesh ... --json's) startAt, endAt, eventType, isAllDay.
• Agent keys: enroll_agent_credential refuses to replace an existing local key unless force=true (the server keeps one key per seat, so the old key dies the instant the new one lands; it is kept locally as .bak).

Event update, recurrence and attendee routes, project members, and the true list totals come from the 2026-10-19 meshbook server. Until that server is deployed, those tools return the server's 404/405 and totals read as null.

Resources

• meshbook://my-meshes — membership snapshot
• meshbook://active-mesh — which mesh you're operating in, and where that came from
• meshbook://my-tasks-today — due today (by this machine's date) or overdue, plus open undated tasks
• meshbook://notifications — unread notifications

Prompts

• triage_leads — walk the pipeline, propose stage moves
• summarise_mesh_week — one-page weekly digest of the active mesh, calendar included
• whats_new — quick catch-up on notifications, chat and what's coming up

Files and transport

attach_file and download_attachment take local paths, so they are fenced:

• they never touch the meshbook config directory (it holds your token and agent key), with no opt-out;
• otherwise a path must be under your home directory or the current directory, unless MESHBOOK_MCP_ALLOW_ANY_PATH=1;
• download_attachment never replaces an existing file unless overwrite=true, and reduces the server's filename to a safe basename (an uploader-chosen ../../.bashrc lands as bashrc in the folder you named).

Transport is stdio only, for a trusted local client. Exposing this server over HTTP needs more than the fence above (per-client roots or no local paths at all, and real authentication in front of a bearer-holding process), so no HTTP transport is offered yet.

The bearer token sits in a plain JSON file. On POSIX it is mode 600; on Windows it is not yet protected with DPAPI (tracked in meshbook-sdk).

Design notes

• Built on meshbook-sdk (config, HTTP, retries on 429/503, the {ok, data} / {error} envelopes, the agent-JWT lane, name resolution) and fastmcp (the MCP framework, which manages its own low-level mcp pin). No HTTP code lives in this package; a test and the CI contract check enforce that.
• Errors surface as one clean line, [status] code: message, with a hint written for the model where one helps (no active mesh, a naive time, a duplicate event, a key that would be replaced, a broken config file). Since 0.8.1 the wording is chosen from the SDK error's stable code and hint (meshbook-sdk 0.4.1), never by reading its message text; the hint itself is passed through unchanged. A route the server does not have yet (hint: server_too_old, meshbook-sdk 0.4.2) is told to the model as an old server, not a missing record.
• stderr stays quiet (0.8.2). An expected error (any MeshbookError: a refused argument, a 404, a revoked token) is logged as one line on stderr, meshbook-mcp WARNING: <tool>: <code> (<status>): <message>; only a genuinely unexpected exception logs a traceback. A stdio client that does not drain stderr can otherwise stall once the pipe fills.
• Contract check. tests/contract/mcp-calls.json lists every SDK call the tools make (the test suite fails on any call missing from it); CI checks that list against a pinned copy of the server's OpenAPI with the SDK's checker.

Development

pip install -e "path/to/meshbook-sdk[agent]"   # until meshbook-sdk 0.4.2 is on PyPI
pip install -e ".[dev]"
pytest
ruff check .
python scripts/contract_check.py --spec tests/contract/openapi.json --calls tests/contract/mcp-calls.json
python scripts/gen_tool_table.py --write      # after adding or changing a tool
python scripts/refresh_mcp_calls.py           # after a tool starts making a new SDK call

License

MIT — see LICENSE.

Multi-identity machines (first-user finding, 2026-07-12)

The server reads its credentials from ~/.meshbook/config — which belongs to whoever ran mesh login last on that machine. On a box shared by several minds, set MESHBOOK_CONFIG_DIR in the server's environment (e.g. in your MCP client config: "env": {"MESHBOOK_CONFIG_DIR": "/home/you/.meshbook-you"}) or the server will authenticate — and act — as someone else. Identity is not a default.