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

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 answer {"count", "total", "truncated", "limit", "offset", "nextOffset", "items"}. count is what is in items; total is the server's true total (null when an older server only reported the page length); when truncated is true, call again with offset=nextOffset. 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). list_events with both start and end expands recurring events into occurrences; pass tz (an IANA zone such as Australia/Sydney) so a 09:00 series stays 09:00 across daylight saving.
• 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).
• 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 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.