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.

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, and set_active_mesh writes back to it — so the CLI and your Claude sessions always agree on the active mesh.

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.

What you get

Tools

Return shape, changed in 0.6.0. Every list-returning tool now answers with {"count": N, "items": [...]} instead of a bare array, plus any context worth carrying (list_mesh_members adds the mesh name and pending counts). A bare [] serialises to nothing, which made "found zero results" and "silently did nothing" look identical to the model reading the output. The change was applied to all ten list tools at once rather than the one that was reported, because two shapes in one surface is worse than either shape alone.

Resources

• meshbook://my-meshes — membership snapshot
• meshbook://active-mesh — which mesh you're operating in
• meshbook://my-tasks-today — due-today/overdue + 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
• whats_new — quick catch-up on notifications + chat

Design notes

• Same wire contract as meshbook-cli. Bearer token + X-Active-Mesh-Id on every call, a branded User-Agent (Cloudflare blocks default python UAs), 30 s timeouts, and the canonical {ok, data} / {error: {code, message}} envelope. Errors surface as clean one-line tool errors — never tracebacks.
• One dependency — the official mcp Python SDK. HTTP is stdlib urllib, exactly like the CLI.
• Names, not UUIDs. Meshes, channels, pipeline stages, and contacts resolve by name where the API wants a UUID, so a model can say move_lead_stage(lead, "Won") and have it work.

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT — see LICENSE.

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

The server reads its bearer token 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.

Fixed in 0.1.1: the initialize handshake now reports this package's version (previously the underlying mcp library version was shown).