@ai-staff/crm-mcp-server

MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more.

Overview

This package implements a Model Context Protocol (MCP) server that connects AI agents (e.g., Paperclip) to the Build Your App CRM system. It exposes 8 dispatcher tools + 1 standalone health check covering all CRM domains: leads, companies, proposals, analysis, tasks, notifications, and admin.

Each dispatcher uses an action + params pattern: one tool per domain, with action selecting the specific operation. This reduces context tokens by ~89% compared to exposing all operations as individual tools.

The server uses stdio transport and is configured via environment variables. A single server instance serves all API roles (CEO, ManagerAPI, AnalystAPI) — the role is determined from the JWT token in CRM_API_KEY.

Installation

npx -y @ai-staff/crm-mcp-server

Or install globally:

npm install -g @ai-staff/crm-mcp-server
crm-mcp-server

Configuration

Set environment variables before starting:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CRM_API_URL | No | https://crm.ai-staff.pro/api/v1 | Base URL of the CRM API | | CRM_API_KEY | Yes | — | JWT API key with appropriate role (CEO, MANAGER_API, ANALYST_API) |

Paperclip Configuration

Add to your Paperclip agent's adapterConfig:

{
  "mcpServers": {
    "crm": {
      "command": "npx",
      "args": ["-y", "@ai-staff/crm-mcp-server@latest"],
      "env": {
        "CRM_API_URL": "https://crm.ai-staff.pro/api/v1",
        "CRM_API_KEY": "<your-api-key>"
      }
    }
  }
}

Role-Based Access

| Role | CRM_API_KEY | Access Level | |------|-------------|--------------| | CEO | Token with apiRole: CEO | Full access (except delete operations) | | ManagerAPI | Token with apiRole: MANAGER_API | Own leads only, limited write | | AnalystAPI | Token with apiRole: ANALYST_API | Read all data, run analyses, no business writes |

Tools (9 total)

Dispatchers (8)

Each dispatcher accepts action + params. Call with action: "list" to discover all available actions.

crm_leads — Leads & Notes (14 actions)

• list_leads — List leads with filtering and pagination
• get_lead — Get lead details by ID
• create_lead — Create a new lead
• update_lead — Update lead fields
• update_lead_status — Change lead status
• archive_lead — Archive a lead
• delete_lead — Soft-delete a lead (ADMIN only)
• get_lead_history — Get lead change history
• add_lead_manual_event — Add manual event to history
• get_users_for_lead_assignment — Get users for assignment
• list_lead_notes — List notes for a lead
• add_lead_note — Add a note to a lead
• update_lead_note — Update a note
• delete_lead_note — Delete a note

crm_companies — Companies & Search (11 actions)

• search_companies — Search companies directory
• search_companies_full — Advanced company search with filters
• get_company — Get company by ID
• count_companies — Count companies by filters
• autocomplete — Company name autocomplete
• get_taxonomy — Get all categories (niches)
• get_locations — Get cities/regions
• add_companies_to_leads — Add companies as leads
• link_company_to_lead — Link company to lead
• unlink_company_from_lead — Unlink company from lead
• copy_company_data_to_lead — Copy company data to lead

crm_proposals — Proposals, Research & Generation (12 actions)

• list_proposals_by_lead — List proposals for a lead
• get_proposal_context — Get context for proposal creation
• create_proposal — Create a new proposal
• update_proposal — Update a proposal
• preview_proposal — Preview a proposal
• start_proposal_research — Start research for a proposal
• get_research_job_status — Check research job status
• get_research_steps — Get research step cache
• get_research_step_history — Get step version history
• invalidate_research_cache — Invalidate research cache (ADMIN only)
• generate_proposal_draft — Generate proposal draft via AI
• regenerate_proposal_section — Regenerate a proposal section

crm_analysis — Analysis & SEO (9 actions)

• run_lead_structure_analysis — Run structure analysis (sitemap, crawl)
• run_ai_scoring — Run AI scoring for a lead
• run_pagespeed_analysis — Run PageSpeed analysis
• generate_ai_audit — Generate AI audit for a site
• start_seo_research — Start SEO research
• get_seo_results — Get SEO results
• get_seo_history — Get SEO analysis history
• save_seo_results — Save SEO results
• get_analysis_job_status — Check analysis job status

crm_batch — Batch Operations & Uploads (9 actions)

• batch_lead_structure — Batch structure analysis for leads
• batch_lead_programmatic — Batch programmatic analysis for leads
• batch_lead_ai_score — Batch AI scoring for leads
• batch_company_programmatic — Batch programmatic analysis for companies
• batch_company_structure — Batch structure analysis for companies
• reanalyze_lead — Re-analyze a lead (selective: tech, mobile, speed)
• start_batch_analysis — Start batch URL analysis
• upload_screenshot — Upload a screenshot (base64)
• upload_prototype — Upload a prototype file (base64)

crm_tasks — Tasks (5 actions)

• list_tasks — List tasks with filtering
• create_task — Create a task
• update_task — Update a task
• delete_task — Delete a task
• get_leads_for_task_select — Get leads for task assignment

crm_notifications — Notifications (4 actions)

• list_notifications — List user notifications
• get_unread_notification_count — Get unread count
• mark_all_notifications_read — Mark all as read
• mark_notification_read — Mark one as read

crm_admin — Users, Settings & Audit (9 actions)

• register_user — Register a new user (ADMIN only)
• update_user — Update user data (ADMIN only)
• list_users — List all users
• get_ai_settings — Get AI settings (ADMIN/CEO/AnalystAPI)
• update_ai_settings — Update AI settings (ADMIN/CEO only)
• list_audit_logs — List audit logs with filtering
• get_audit_log — Get audit log details
• cleanup_audit_logs — Cleanup old audit logs (ADMIN only)
• cleanup_audit_log_details — Cleanup old audit log details (ADMIN only)

Standalone (1)

crm_health_check — Health Check

• No params. Returns { status, latency, version }.

Discovery

Call any dispatcher with action: "list" (and empty params) to see all available actions with their HTTP methods and endpoints:

{
  "tool": "crm_leads",
  "params": {
    "action": "list",
    "params": {}
  }
}

Response:

{
  "available_actions": [
    { "name": "list_leads", "description": "...", "method": "GET", "endpoint": "/leads" },
    ...
  ],
  "hint": "Pass action='name' and params={...} to execute."
}

Migration from v1.x

Before (v1.x):

{ "tool": "crm_list_leads", "params": { "status": "NEW", "limit": 20 } }

After (v2.0):

{ "tool": "crm_leads", "params": { "action": "list_leads", "params": { "status": "NEW", "limit": 20 } } }

See CHANGELOG.md for full migration guide.

Development

cd packages/crm-mcp-server
npm install
npm run build
npm run inspect  # Test with MCP Inspector

Error Handling

All errors are transformed into actionable messages for AI agents:

| HTTP Code | Message | |-----------|---------| | 400 | Invalid request: [details]. Check the parameters and try again. | | 401 | Authentication failed. The API key is invalid or expired. | | 403 | You don't have permission to perform this action. | | 404 | Resource not found. | | 409 | This resource is locked by another user or has been modified. | | 429 | Rate limit exceeded. Retry after N seconds. | | 500 | CRM is temporarily unavailable. Please try again later. |

Pagination

All list endpoints support pagination with page and limit parameters. Default limit is 20, maximum is 100. Responses exceeding 25,000 characters are truncated with a message indicating how to get more data.

License

Private — Internal use only.