# soil-dev/capsulemcp [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/soil-dev/capsulemcp  
**GitHub Stars:** 5  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/soil-dev-capsulemcp

## Description
MCP server for Capsule CRM. 81 tools (49 in read-only mode) covering contacts, opportunities, projects, tasks, timeline activity, structured + saved filters, workflow tracks, and file attachments. Two transports — stdio (npx capsulemcp) and HTTP+OAuth for hosted Custom Connectors. Read-only-mode env flag for safer defaults. Apache 2.0.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "capsulemcp": {
    "command": "npx",
    "args": ["-y","cache"],
    "env": {
      "CAPSULE_API_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `CAPSULE_API_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What soil-dev/capsulemcp MCP server does

soil-dev/capsulemcp gives MCP clients access to the Capsule CRM resource graph. It covers people and organisations, opportunities, projects, tasks, notes and captured emails, attachments, timeline activity, deleted-record audits, pipelines, milestones, boards, stages, workflow tracks, saved filters, custom fields, tags, users, teams, and reference metadata.

The server supports both retrieval and mutation. Read tools can search, filter, fetch, list, and batch-fetch records. Write tools can create or update records, add notes and attachments, manage contact details and tags, apply workflow tracks, and perform other CRM changes. Whole-record deletion and selected removal operations require an explicit confirmation argument.

## How it works

Local clients launch the package through stdio, while hosted deployments can use HTTP with OAuth for Custom Connectors. Capsule API authentication is supplied through an environment variable containing an API token. The token's permissions remain the upper limit on what the server can do.

Most list operations are paginated. Record lists generally return up to 25 items by default, reference-data lists default to 100, and supported calls can request up to 100 items per page. Larger responses provide a next-page cursor. Batch-fetch tools can retrieve up to 50 records in one call.

Structured filter tools accept multiple field, operator, and value conditions, combined with AND logic. For sortable results, saved filters created in Capsule's web interface can be discovered and run through the server. Many retrieval tools also support validated embed options for related data such as tags and custom fields.

## Setup and configuration

Create a Capsule API token from the account's API Authentication Tokens settings. For a local Claude Desktop setup, configure an MCP server that runs `npx` with the `capsulemcp` package and pass `CAPSULE_API_TOKEN` in its environment. Restart the client after saving the configuration so the tools become available. Claude Code can use the local installation path as well.

Set `CAPSULE_MCP_READONLY=1` to prevent write and delete tools from being registered. Pairing this setting with a Capsule token limited to the Read scope provides protection at both the MCP and API layers. Hosted Custom Connector deployments use the HTTP and OAuth transport; an unauthenticated health endpoint is available for token-health and uptime monitoring.

## Tools and capabilities

Capabilities include:

- Searching, filtering, listing, and fetching parties, opportunities, projects, tasks, and entries.
- Creating and editing CRM records, tasks, notes, contact methods, tags, and attachments.
- Uploading files and reading attachment records.
- Running saved searches and inspecting custom fields, teams, users, pipelines, boards, and reference data.
- Reading activity feeds and deleted-record audit lists.
- Managing workflow track instances and additional parties on multi-party deals.
- Using batch operations for mass-update workflows.

Tool annotations identify read-only operations and destructive operations for clients that use MCP safety hints.

## Limitations and notes

Capsule's structured filter endpoint does not provide ad hoc sorting. For recent-record queries, filtering by a date condition and selecting the highest numeric ID can be used because Capsule IDs increase monotonically. Saved filters are the appropriate option when ordering is required.

Read-only mode removes mutation tools at the MCP layer, but it does not replace Capsule token permissions. Destructive calls still require confirmation when write tools are enabled. Pagination must be handled when results exceed the requested page size, and embed tokens vary by resource and are validated per tool.

_Full upstream README: https://allmcps.com/mcp/soil-dev-capsulemcp/readme_