capsulemcp is a Model Context Protocol (MCP) server built for Capsule CRM, whose main purpose is to enable Claude (including Claude Desktop, Claude Code, and web Projects connected through a Custom Connector) to access and operate records in Capsule CRM using natural language. It covers the complete record graph including contacts, organizations, opportunities, projects, tasks, and timeline activities, and supports structured filtering, saved searches, workflow tracks, file attachments, deleted record auditing, and batch retrieval capabilities.
In terms of main capabilities, the server provides 92 tools covering the Capsule resource graph, of which 53 tools are available in read-only mode. It includes complete read coverage, as well as write operations gated by confirmation; there are also 6 batch write tools (batch_) for batch updating workflows. The tools support structured filtering, wrapping Capsule's structured filtering endpoint through the filter_ tools, accepting an array of {field, operator, value} conditions, with conditions related by AND. Because the Capsule API does not support ad hoc sorting, for "most recent X" type questions, it is recommended to filter by date conditions and select the largest id in the results (Capsule's numeric IDs increase monotonically). If sortable queries are needed, saved filters can be used: first create a filter in the Capsule web interface (conditions, columns, and orderBy can be set), then call its id through run_saved_filter, and use list_saved_filters to discover available filters. In addition, it also supports workflow tracks (templates and instances), file attachments (read and write), deleted record auditing, and batch retrieval of up to 50 records per call.
In terms of usage, two transport methods are supported: stdio for local installation (Claude Desktop / Code), and HTTP+OAuth for hosted Custom Connectors, and it provides an unauthenticated GET /health token health page for uptime monitoring. For most individual users, installation only requires pasting a JSON snippet into Claude Desktop's configuration. The quick start steps are: first, in Capsule, generate an API token (My Preferences → API Authentication Tokens → Generate, choose the Read scope for security); then add the configuration to claude_desktop_config.json (on macOS the path is ~/Library/Application Support/Claude/claude_desktop_config.json), with the configuration content being: { "mcpServers": { "capsule": { "command": "npx", "args": ["-y", "capsulemcp"], "env": { "CAPSULE_API_TOKEN": "<paste token here>", "CAPSULE_MCP_READONLY": "1" } } } }; finally restart Claude Desktop, and the Capsule tools will appear in the tool selector. The first launch will fetch the package from npm (a few seconds), and subsequent launches load instantly from the npx cache. To pin a specific version, use "capsulemcp@2.4.0" in args; if tracking a fork or an unpublished branch, the GitHub-ref form can be used: "github:soil-dev/capsulemcp#v2.4.0".
In terms of pagination and parameters, most record list tools default to perPage=25; reference data tools default to perPage=100, so small accounts can usually fit in a single response. All paginated tools have a perPage upper limit of 100, and return a nextPage cursor when there are more results. Many GET tools accept an embed parameter (for example tags, fields), and each tool's description lists its valid tokens (validated by resource; unknown tokens are rejected rather than silently ignored, and the caller-facing project token is mapped to Capsule's legacy kase during transport).
In terms of security and limitations, all write/delete tools can be disabled at the MCP layer by setting CAPSULE_MCP_READONLY=1 (create_, update_, complete_task, add_note, or delete_* are not registered). It is recommended to pair this with a Capsule token that has Read scope to achieve defense in depth—regardless of environment variables, the token's scope is a hard upper limit. Every whole-record deletion tool, as well as remove_track and remove_additional_party, requires confirm: true in its parameters; otherwise the schema will reject the call before issuing any HTTP request. The tool descriptions instruct Claude to first read the entity and confirm with the user before calling. This combined design—read-only scope token, read-only mode flag, schema-level confirmation gating—means that destructive operations happen intentionally, not accidentally. Regarding MCP tool annotations, 53 read tools have readOnlyHint: true, and 8 destructive tools have destructiveHint: true; clients that respect these hints can automatically approve safe reads while still prompting for write/destructive calls. The project uses the Apache License 2.0, with copyright owned by Anton Arapov (2026).
