Imported from pdovhomilja/nextcrm-app (public/SKILL.md). Install upstream with npx skills add pdovhomilja/nextcrm-app --skill public. Copyright stays with the author.

NextCRM MCP Server Skill

Use the NextCRM MCP server to read and write CRM data. This skill documents all available tools and how to use them.

Connection Setup

The server supports two MCP transports. Pick one — most modern clients (Claude Code, Cursor) work with either.

Option A — Streamable HTTP (recommended)

Single POST endpoint. Simpler, the current MCP spec default.

{
  "mcpServers": {
    "nextcrm": {
      "type": "http",
      "url": "https://YOUR_NEXTCRM_URL/api/mcp/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

Option B — SSE (legacy, for older clients)

Two endpoints: a GET SSE stream and a POST message channel. The client opens /api/mcp/sse, the server announces the matching /api/mcp/message?sessionId=… endpoint over the stream, and the client POSTs JSON-RPC there.

{
  "mcpServers": {
    "nextcrm": {
      "type": "sse",
      "url": "https://YOUR_NEXTCRM_URL/api/mcp/sse",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}

You only configure the /sse URL — the client discovers the message endpoint automatically.

Notes

• Replace YOUR_NEXTCRM_URL with your NextCRM instance URL (e.g. http://localhost:3000 for local dev)
• Replace YOUR_API_TOKEN with a token generated from Profile > Developer > API Tokens
• Token prefix: nxtc__
• Some clients omit the type field and infer the transport from the URL — both forms above include it explicitly for clarity

Authentication

All tools require a valid Bearer token. Tokens are generated from the Developer tab in your profile settings. Each token is SHA-256 hashed — the raw value is shown only once at creation.

Available Tools

Accounts (6 tools)

• crm_list_accounts — List CRM accounts assigned to the authenticated user
• crm_get_account — Get a single CRM account by ID
• crm_search_accounts — Search accounts by name or website (substring match)
• crm_create_account — Create a new CRM account
• crm_update_account — Update an existing CRM account by ID (accepts assigned_to to reassign the owner)
• crm_delete_account — Soft-delete a CRM account by ID (sets deletedAt timestamp)

Contacts (6 tools)

• crm_list_contacts — List CRM contacts assigned to the authenticated user
• crm_get_contact — Get a single CRM contact by ID
• crm_search_contacts — Search contacts by name, email, or phone (substring match)
• crm_create_contact — Create a new CRM contact
• crm_update_contact — Update an existing CRM contact by ID (accepts assigned_to to reassign, account to link/unlink a parent account)
• crm_delete_contact — Soft-delete a CRM contact by ID (sets deletedAt timestamp)

Leads (6 tools)

• crm_list_leads — List CRM leads assigned to the authenticated user
• crm_get_lead — Get a single CRM lead by ID
• crm_search_leads — Search leads by name, company, or email (substring match)
• crm_create_lead — Create a new CRM lead
• crm_update_lead — Update an existing CRM lead by ID (accepts assigned_to to reassign the owner)
• crm_delete_lead — Soft-delete a CRM lead by ID (sets deletedAt timestamp)

Opportunities (6 tools)

• crm_list_opportunities — List CRM opportunities assigned to the authenticated user
• crm_get_opportunity — Get a single CRM opportunity by ID
• crm_search_opportunities — Search opportunities by name or description (substring match)
• crm_create_opportunity — Create a new CRM opportunity
• crm_update_opportunity — Update an existing CRM opportunity by ID (accepts assigned_to to reassign, account/contact to link/unlink)
• crm_delete_opportunity — Soft-delete a CRM opportunity by ID

Targets (6 tools)

• crm_list_targets — List CRM targets created by the authenticated user
• crm_get_target — Get a single CRM target by ID
• crm_search_targets — Search targets by name, email, or company (substring match)
• crm_create_target — Create a new CRM target
• crm_update_target — Update an existing CRM target by ID
• crm_delete_target — Soft-delete a CRM target by ID (sets deletedAt timestamp)

Products (5 tools)

Writes (create/update/delete) require a manager or admin role; reads are open to all roles.

• crm_list_products — List CRM products (org-wide catalog)
• crm_get_product — Get a single CRM product by ID
• crm_create_product — Create a new CRM product
• crm_update_product — Update an existing CRM product by ID
• crm_delete_product — Soft-delete a CRM product (sets deletedAt timestamp)

Contracts (5 tools)

• crm_list_contracts — List CRM contracts (org-wide)
• crm_get_contract — Get a single CRM contract by ID with line items
• crm_create_contract — Create a new CRM contract with optional line items
• crm_update_contract — Update an existing CRM contract by ID (does not modify line items)
• crm_delete_contract — Soft-delete a CRM contract (sets deletedAt timestamp)

Activities (5 tools)

• crm_list_activities — List CRM activities created by the authenticated user, optionally filtered by linked entity
• crm_get_activity — Get a single CRM activity by ID with entity links
• crm_create_activity — Create a CRM activity (call/meeting/note/email) and link to entities
• crm_update_activity — Update an existing CRM activity by ID
• crm_delete_activity — Soft-delete a CRM activity by ID (sets deletedAt timestamp)

Documents (8 tools)

• crm_list_documents — List documents, optionally filtered by linked entity type and ID
• crm_get_document — Get a single document by ID
• crm_create_document — Create a document record and get a presigned upload URL
• crm_get_upload_url — Get a presigned upload URL for an existing document
• crm_get_download_url — Get a presigned download URL for a document
• crm_link_document — Link a document to an entity (account, contact, lead, opportunity, or task)
• crm_unlink_document — Remove a document link from an entity
• crm_delete_document — Soft-delete a document (sets status to DELETED)

Target Lists (7 tools)

• crm_list_target_lists — List target lists (org-wide)
• crm_get_target_list — Get a target list by ID with its members
• crm_create_target_list — Create a new target list
• crm_update_target_list — Update a target list by ID
• crm_delete_target_list — Soft-delete a target list (sets deletedAt timestamp)
• crm_add_to_target_list — Add one or more targets to a target list
• crm_remove_from_target_list — Remove one or more targets from a target list

Enrichment (4 tools)

• crm_enrich_contact — Enrich a single contact using Firecrawl + AI (requires API keys configured)
• crm_enrich_contact_bulk — Enrich multiple contacts in bulk (max 100, dispatches async jobs)
• crm_enrich_target — Enrich a single target using Firecrawl + AI (requires API keys configured)
• crm_enrich_target_bulk — Enrich multiple targets in bulk (max 100, dispatches async jobs)

Email Accounts (1 tool)

• crm_list_email_accounts — List the authenticated user's connected email accounts

Users (1 tool)

• crm_list_users — List NextCRM users to resolve a person to the user ID that assigned_to needs. Returns active users by default; managers and admins additionally see email, role, status, and last login

Campaigns (19 tools)

• campaigns_list — List campaigns (org-wide)
• campaigns_get — Get a campaign by ID with steps and stats summary
• campaigns_create — Create a new campaign
• campaigns_update — Update a campaign by ID
• campaigns_delete — Soft-delete a campaign (sets deletedAt timestamp)
• campaigns_send — Trigger sending a campaign (must be in draft or scheduled status)
• campaigns_pause — Pause an active/sending campaign
• campaigns_resume — Resume a paused campaign
• campaigns_list_templates — List campaign email templates (org-wide)
• campaigns_get_template — Get a campaign template by ID
• campaigns_create_template — Create a campaign email template
• campaigns_update_template — Update a campaign template by ID
• campaigns_delete_template — Soft-delete a campaign template (sets deletedAt timestamp)
• campaigns_create_step — Add a step to a campaign sequence
• campaigns_update_step — Update a campaign step by ID
• campaigns_delete_step — Delete a campaign step by ID
• campaigns_assign_target_list — Assign a target list to a campaign
• campaigns_remove_target_list — Remove a target list from a campaign
• campaigns_get_stats — Get send/open/click/unsubscribe stats for a campaign

Projects (18 tools)

• projects_list_boards — List project boards the user owns or is shared with
• projects_get_board — Get a project board with its sections and tasks
• projects_create_board — Create a new project board
• projects_update_board — Update a project board by ID
• projects_delete_board — Soft-delete a project board (sets deletedAt timestamp)
• projects_create_section — Add a section (column) to a board
• projects_update_section — Update a section title or position
• projects_delete_section — Delete a section (must be empty)
• projects_list_tasks — List tasks, optionally filtered by board, section, user, or status
• projects_get_task — Get a task by ID with comments and documents
• projects_create_task — Create a task in a board section
• projects_update_task — Update a task by ID
• projects_move_task — Move a task to a different section and/or position
• projects_delete_task — Soft-delete a task
• projects_add_comment — Add a comment to a task
• projects_list_comments — List comments on a task
• projects_assign_document — Link a document to a task
• projects_watch_board — Watch or unwatch a project board

Reports (2 tools)

• reports_list — List available report configurations
• reports_run — Run a report by category and get the data

Common Workflows

Research a company and create an account

1. crm_search_accounts — check if it already exists
2. crm_create_account — create the account with company details
3. crm_create_contact — add key contacts
4. crm_create_activity — log the research as a note

Build a prospecting campaign

1. crm_create_target_list — create a target list
2. crm_create_target (repeated) — add prospects
3. crm_add_to_target_list — add targets to the list
4. campaigns_create — create the campaign
5. campaigns_create_template — create email template
6. campaigns_create_step — add sequence steps
7. campaigns_assign_target_list — connect target list to campaign
8. campaigns_send — launch the campaign

Track a deal pipeline

1. crm_list_opportunities — review current pipeline
2. crm_create_opportunity — add new deal
3. crm_create_activity — log meetings and calls
4. crm_link_document — attach proposals
5. crm_update_opportunity — update stage/amount as deal progresses

Enrich contacts with AI

1. crm_list_targets or crm_search_targets — find targets to enrich
2. crm_enrich_target_bulk — enrich up to 100 targets at once
3. crm_get_target — check enrichment results

Reassign records to another user

1. crm_list_users — resolve the person's name to a user ID (query does a substring match on name)
2. crm_update_account / crm_update_contact / crm_update_lead / crm_update_opportunity — set assigned_to to that ID
3. Pass assigned_to: null instead to unassign; omit it entirely to leave the current owner alone

A member token can only reassign records it already owns, and the target must be an ACTIVE user — otherwise the update returns NOT_FOUND.

Project management

1. projects_create_board — create a project board
2. projects_create_section — add columns (To Do, In Progress, Done)
3. projects_create_task — add tasks
4. projects_move_task — move tasks between sections
5. projects_add_comment — discuss tasks

Notes

• All list operations support pagination (cursor-based)
• Search operations use substring matching
• Delete operations are soft-deletes (set deletedAt, recoverable via admin audit log)
• Reads are scoped by the token owner's role, matching the web UI: admin and manager tokens see all non-deleted records, member tokens see only their own
• Writes are gated per-record. A denied write returns NOT_FOUND rather than FORBIDDEN, so a failure never confirms a record exists
• assigned_to accepts an active user ID (reassign) or explicit null (unassign); omitting it leaves the owner untouched. Use crm_list_users to resolve the ID
• Enrichment tools require API keys (OpenAI + Firecrawl) configured at system or user level