soil-dev/capsulemcp

A Model Context Protocol server for Capsule CRM. Connect Claude (Desktop, Code, or web Projects via Custom Connector) to your CRM and let it answer natural-language questions across the full record graph: contacts, organisations, opportunities, projects, tasks, and timeline activity. Beyond the basics it covers structured filters with field/operator conditions, saved searches with sort, workflow tracks (templates and instances), file attachments (read + write), audit of deleted records, and batch fetches up to 50 records per call.
- **92 tools** across the Capsule resource graph (53 in read-only mode) — full read coverage plus careful, confirm-gated writes; 6 batched-write tools (batch_*) for mass-update workflows
- **Two transports**: stdio for local installs (Claude Desktop / Code), HTTP+OAuth for hosted Custom Connectors — with an unauthenticated GET /health token-health page for uptime monitoring
- **Read-only mode** as a one-env-var flag; works alongside read-scoped Capsule tokens
- **MCP tool annotations**: 53 read tools carry readOnlyHint: true, 8 destructive ones carry destructiveHint: true — clients that honor these hints can auto-approve safe reads while still prompting for writes/destructive calls
- **Apache 2.0**
Pick your install
| You want | Read this |
|---|---|
| Example questions to ask once the connector is running | EXAMPLES.md |
| To use it locally with Claude Desktop or Claude Code | INSTALL.md |
| To deploy it once and have your whole team use it via Claude.ai | DEPLOY.md |
| To wire it into n8n workflows | INTEGRATIONS-n8n.md |
| To contribute, debug, add a tool, or cut a release | HOWTO.md (procedures) · CONTRIBUTING.md (style & PR checks) |
| To understand what's intentionally not implemented (and why) | DESIGN.md |
| To see what performance work has been done (and what's next) | OPTIMIZATIONS.md |
| To see ideas for features that might land in future versions | IDEAS.md |
| To learn the surprising parts of Capsule's v2 API (with verbatim doc quotes) | NOTES-ON-CAPSULE-API.md |
For most individual users the install is a single JSON snippet pasted into Claude Desktop's config — see INSTALL.md.
Quick start (Claude Desktop)
1. Generate a Capsule API token: **My Preferences → API Authentication Tokens → Generate**, choose the **Read** scope for safety.
2. Add this to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
3. Restart Claude Desktop. The Capsule tools appear in the tool picker.
That's it. The first launch fetches the package from npm (a few seconds); subsequent launches are instant from the npx cache. To pin a specific version, use "capsulemcp@2.4.0" in args. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: "github:soil-dev/capsulemcp#v2.4.0" — same arguments, just installs from a git clone rather than the npm registry. See INSTALL.md for the Claude Code path, manual install, and troubleshooting.
Tools
| Group | Read | Write |
|---|---|---|
| Parties (people/orgs) | search_parties, filter_parties, get_party, get_parties, list_employees, list_party_opportunities, list_party_projects, list_party_entries | create_party, update_party, delete_party, add_party_email_address, remove_party_email_address_by_id, add_party_phone_number, remove_party_phone_number_by_id, add_party_address, remove_party_address_by_id, add_party_website, remove_party_website_by_id |