Capsulemcp

What soil-dev/capsulemcp MCP server does

The soil-dev/capsulemcp MCP server exposes Capsule CRM through Model Context Protocol tools. It lets compatible clients work with the connected Capsule account’s people, organisations, opportunities, projects, tasks, notes, captured emails, attachments, activity, workflow tracks, tags, users, teams, and reference data.

The server provides read operations across the resource graph and write operations for supported records. It also includes structured filtering, saved-filter execution, deleted-record audit views, and batch fetches that can retrieve up to 50 records per call. File attachments support both retrieval and upload. The tool set is described in the repository as 92 tools in normal mode and 53 when read-only mode is enabled.

How it works

A Capsule API token authenticates local usage. MCP clients invoke tools such as searches, record lookups, list operations, structured filters, and saved-filter runs. Paginated endpoints generally return up to 100 records per page and provide a cursor when more results are available. Standard record lists default to 25 items per page, while reference-data lists default to 100.

Structured filter tools accept multiple field, operator, and value conditions that are combined with AND logic. Capsule does not provide ad-hoc sorting for these filters, so saved filters are the option for queries that need a configured order. Saved filters are created in Capsule’s web interface and then discovered or executed through MCP.

Setup and configuration

For a local Claude Desktop setup, install the package through npx and provide the Capsule token as an environment variable:

{
  "mcpServers": {
    "capsule": {
      "command": "npx",
      "args": ["-y", "capsulemcp"],
      "env": {
        "CAPSULE_API_TOKEN": "your-token",
        "CAPSULE_MCP_READONLY": "1"
      }
    }
  }
}

Restart the client after adding the configuration. The CAPSULE_MCP_READONLY setting is optional; when set to 1, write and delete tools are not registered. The repository recommends pairing this setting with a Capsule token using the Read scope. The token’s permissions remain the upper limit on what the server can do.

The soil-dev/capsulemcp MCP server also supports HTTP with OAuth for hosted Custom Connectors.

Tools and capabilities

Supported areas include:

• Search, filtering, retrieval, listing, creation, and updates for parties, opportunities, projects, and tasks.
• Notes, captured-email entries, timeline activity, deleted-record audits, and related records.
• File attachment download and upload.
• Pipelines, milestones, project boards, stages, workflow track definitions, and track instances.
• Saved filters, custom-field metadata, tags, users, teams, and Capsule reference data.
• Batch read and batch write tools for mass-update workflows.

Read tools carry read-only annotations, and destructive tools carry destructive annotations for clients that honor MCP tool hints. Whole-record deletes, track removal, and removal of additional parties require an explicit confirm: true argument.

Limitations and notes

Read-only mode disables write and delete tools at the MCP layer, but it does not replace Capsule token permissions. Pagination still requires following the returned cursor when results exceed a page. Filter results cannot be freely sorted; use a saved filter when ordering matters. Valid embed values differ by resource and are checked by each tool, so unsupported values are rejected. The project embed name used by callers maps to Capsule’s legacy API term on the wire.

The soil-dev/capsulemcp MCP server is licensed under Apache License 2.0.