convez.ai
MCP ServerIntegração & APIsIntermediário
soil-dev

Capsule CRM MCP Server

soil-dev/capsulemcp

Acesso completo ao Capsule CRM dentro do Claude com 89 ferramentas

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta Claude ao Capsule CRM, permitindo consultas em linguagem natural sobre contatos, organizações, oportunidades, projetos e tarefas. Oferece 89 ferramentas com suporte a leitura completa, escritas confirmadas e modo somente-leitura, instalável localmente via npx ou em toda organização via Custom Connectors.

Instalação

$npx convez-ai soil-dev/capsulemcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
1
Acompanhando
0
Saúde
75%
Último commit
há 5 dias
Versão
v2.5.0
Issues abertas
3
Contribuidores
2

Casos de uso

  • Consultar informações de contatos e oportunidades em linguagem natural
  • Automatizar operações em massa no CRM com ferramentas batch
  • Integrar Capsule em fluxos de trabalho do Claude Desktop ou Custom Connectors
  • Auditar registros deletados e acompanhar histórico de atividades

Veredito

MCP robusto e bem documentado para Capsule CRM com cobertura ampla (89 ferramentas), segurança via modo read-only e suporte multi-transporte. Implementação séria com hints de controle de acesso, ideal para equipes que usam Capsule como sistema central.

README

A tradução para o português deste README ainda está na fila.

capsulemcp

capsulemcp MCP server

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.

  • 89 tools across the Capsule resource graph (50 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
  • Read-only mode as a one-env-var flag; works alongside read-scoped Capsule tokens
  • MCP tool annotations: 50 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 wantRead this
Example questions to ask once the connector is runningEXAMPLES.md
To use it locally with Claude Desktop or Claude CodeINSTALL.md
To deploy it once and have your whole team use it via Claude.aiDEPLOY.md
To wire it into n8n workflowsINTEGRATIONS-n8n.md
To contribute, debug, add a tool, or cut a releaseHOWTO.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 versionsIDEAS.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):

    {
      "mcpServers": {
        "capsule": {
          "command": "npx",
          "args": ["-y", "capsulemcp"],
          "env": {
            "CAPSULE_API_TOKEN": "<paste token here>",
            "CAPSULE_MCP_READONLY": "1"
          }
        }
      }
    }
    
  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.1.1" in args. If you're tracking a fork or an unreleased branch, use the GitHub-ref form instead: "github:soil-dev/capsulemcp#v2.1.1" — 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

GroupReadWrite
Parties (people/orgs)search_parties, filter_parties, get_party, get_parties, list_employees, list_party_opportunities, list_party_projects, list_party_entriescreate_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
Opportunitiessearch_opportunities, filter_opportunities, get_opportunity, get_opportunities, list_opportunity_entries, list_associated_projectscreate_opportunity, update_opportunity, delete_opportunity
Projectssearch_projects, list_projects, filter_projects, get_project, get_projects, list_project_entriescreate_project, update_project, delete_project
Additional parties (multi-party deals)list_additional_partiesadd_additional_party, remove_additional_party
Taskslist_tasks, get_task, get_taskscreate_task, update_task, complete_task, delete_task
Entries (notes / captured emails)get_entry, list_entriesadd_note, update_entry, delete_entry
Attachments (file upload / download)get_attachmentupload_attachment
Audit (deleted records)list_deleted_parties, list_deleted_opportunities, list_deleted_projects—
Pipelines & milestones (opportunities)list_pipelines, list_milestones—
Boards & stages (projects)list_boards, list_stages—
Tracks (workflow instances)list_track_definitions, list_entity_tracks, get_trackapply_track, update_track, remove_track
Saved filterslist_saved_filters, run_saved_filter—
Custom fields (schema)list_custom_fields, get_custom_field—
Tagslist_tagsadd_tag, remove_tag_by_id, delete_tag_definition
Users & teamslist_users, get_current_user, list_teams—
Reference metadatalist_lost_reasons, list_activity_types, list_categories, list_goals, get_site—

Most record-list tools default perPage=25; reference-data tools default perPage=100 so small accounts usually fit in one response. All paginated tools cap perPage at 100 and return a nextPage cursor when more results exist. Many GET tools accept an embed parameter (e.g. tags,fields) — see Capsule's API docs for the full list per resource.

The filter_* tools wrap Capsule's structured filter endpoint (POST /<entity>/filters/results) and accept an array of {field, operator, value} conditions ANDed together. Capsule's API does not support ad-hoc sort, so for "most recent X" questions filter by a date condition (e.g. addedOn is within last 7) and pick the highest id from the result — Capsule's numeric IDs are monotonically incrementing.

If you want sortable queries, use saved filters instead. Create the filter once in Capsule's web UI (it lets you set conditions, columns, and orderBy), then call run_saved_filter with its id. Use list_saved_filters to discover what's available.

Read-only mode

Set CAPSULE_MCP_READONLY=1 to disable every write/delete tool at the MCP layer (none of create_*, update_*, complete_task, add_note, or delete_* are registered). Pair it with a Capsule token that has the Read scope for defence in depth — your token's scope is the hard ceiling regardless of the env var.

Delete safety

Every whole-record delete_* tool, plus remove_track and remove_additional_party, requires confirm: true in its arguments. Without it, the schema rejects the call before any HTTP is made. Tool descriptions tell Claude to read the entity first and confirm with the user before invoking. The combined design — read-scoped token, read-only mode flag, schema-level confirm gate — means destructive actions are deliberate, not accidental.

License

Apache License 2.0 — Copyright 2026 Anton Arapov.

Ver o original no GitHub

Bom para

Relacionados