@bendyline/gezel-mcp

The Model Context Protocol server that gives gezels, the AI companions in Gezel, their hands.

Every tool a gezel can call lives here: memory search and save, workspace file operations, project artifacts, the shared document library, script and Playwright execution, task management, team and project management, image rendering, and history search.

Gezel runs this server for every gezel's chat. You can also run it from any other MCP client, so that client works with your gezels' memories, projects, and tasks.

npm install @bendyline/gezel-mcp

It speaks stdio, so any MCP client can run it. With Gezel running on the same computer:

{
  "mcpServers": {
    "gezel": {
      "command": "npx",
      "args": ["-y", "@bendyline/gezel-mcp"],
      "env": {
        "GEZEL_AGENT_ID": "<a gezel id from `gezel agent list`>",
        "GEZEL_PROJECT_ID": "default"
      }
    }
  }
}

There is no address, password, or certificate to configure. The server is a thin front end that calls back into the running Gezel service, and finds it on its own: Gezel picks its port, its sign-in token, and its TLS certificate at each launch and writes them to ~/.gezel/runtime/ (port, auth-token, cert.pem), readable only by you. The server reads them when it starts and follows Gezel across a restart, so a long-lived MCP client keeps working after Gezel updates. If Gezel is not running when the client starts the server, it exits with a message saying to open the Gezel app or run gezel start; start it, then reconnect the server from your MCP client.

| Variable | | |---|---| | GEZEL_AGENT_ID | The gezel the tools work as: whose memories they search and save, whose tasks they see. | | GEZEL_PROJECT_ID | The project tools use when a call names none. Default default. | | GEZEL_HOME | A Gezel home other than ~/.gezel. |

Run this way, the server acts with your own access, as the gezel command does; GEZEL_PROJECT_ID picks a default, not a boundary.

gezel agent list (from @bendyline/gezel-cli) lists your gezels and their ids. The agent in that command and in GEZEL_AGENT_ID is a historical name: both refer to your gezels.

When Gezel starts the server itself, for a gezel's chat, it passes the connection directly: GEZEL_BASE_URL, GEZEL_TOKEN (a token it mints for that one session, confined to its project unless the gezel coordinates across projects), and GEZEL_CERT_PATH (the runtime/cert.pem that token's service is using). Setting GEZEL_BASE_URL yourself turns the lookup off, and keeping all three current across restarts is then up to you.

Tool categories

Memory · workspace files · project artifacts · shared documents · script and Playwright execution · package installation · team and project management · tasks · user questions · history search · image rendering.

Run the server and call tools/list for the authoritative, current inventory.

Entry points

| Subpath | Contents | |---|---| | @bendyline/gezel-mcp | Server construction helpers | | @bendyline/gezel-mcp/lint-contracts | The exact input and output schemas the built-in tools publish, for checking tool contracts | | @bendyline/gezel-mcp/dist/server.js | The stdio server itself, also installed as the gezel-mcp command. The Gezel service launches this file for every chat, so it stays a supported path |

Stability

Public API under semver. Tool names and argument schemas are part of that contract: removing a tool or narrowing an argument is a breaking change.

MIT © Bendyline