@theyahia/amocrm-mcp

Production-grade MCP server for amoCRM API. 19 tools covering leads, contacts, companies, pipelines, tasks, notes, search, events, and unsorted leads. OAuth 2.0 with automatic token refresh. Rate limiting (7 req/sec). Retry with exponential backoff.

Installation

npx -y @theyahia/amocrm-mcp

MCP Configuration

Add to your Claude Desktop, Cursor, or any MCP client config:

{
  "mcpServers": {
    "amocrm": {
      "command": "npx",
      "args": ["-y", "@theyahia/amocrm-mcp"],
      "env": {
        "AMOCRM_SUBDOMAIN": "mycompany",
        "AMOCRM_ACCESS_TOKEN": "your-access-token",
        "AMOCRM_REFRESH_TOKEN": "your-refresh-token",
        "AMOCRM_CLIENT_ID": "your-client-id",
        "AMOCRM_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
AMOCRM_SUBDOMAIN	Yes	Your amoCRM subdomain (e.g. mycompany from mycompany.amocrm.ru)
AMOCRM_ACCESS_TOKEN	Yes	OAuth access token
AMOCRM_REFRESH_TOKEN	No	OAuth refresh token (enables auto-refresh on 401)
AMOCRM_CLIENT_ID	No	OAuth client ID (required for token refresh)
AMOCRM_CLIENT_SECRET	No	OAuth client secret (required for token refresh)

AMOCRM_DOMAIN is also accepted as an alias for AMOCRM_SUBDOMAIN (backwards compatibility).

Tools (19)

Leads

Tool	Description
list_leads	Search and list deals with filters (pipeline, statuses, query). Embed contacts, loss reasons.
get_lead	Get a single lead by ID with linked contacts and catalog elements.
create_lead	Create a new lead with name, price, pipeline, status, custom fields.
update_lead	Update lead fields — move between stages, change price, reassign.

Contacts

Tool	Description
list_contacts	Search contacts by name, phone, email.
get_contact	Get a single contact with all custom fields.
create_contact	Create a contact with phone, email, and custom fields.

Companies

Tool	Description
list_companies	Search companies. Embed linked leads and contacts.
create_company	Create a company with custom fields.

Pipelines

Tool	Description
list_pipelines	List all sales pipelines with their statuses (stages).

Tasks

Tool	Description
list_tasks	List tasks filtered by entity, completion, responsible user.
create_task	Create a task linked to a lead/contact/company with deadline.
complete_task	Mark task as done and add result text.

Unsorted

Tool	Description
list_unsorted	List incoming unsorted leads (forms, email parsing).
accept_unsorted	Accept an unsorted lead into a pipeline.

Notes

Tool	Description
add_note	Add a note (common, call_in, call_out, service_message) to any entity.

Search

Tool	Description
search	Universal search across leads, contacts, and companies.

Events

Tool	Description
list_events	Activity log — status changes, calls, notes, links.

Account

Tool	Description
get_account	Account info, users, task types, amojo settings.

Demo Prompts

Sales overview:

"Show me all leads in the 'Sales' pipeline that are currently in the 'Negotiation' stage. Include contact info."

Task management:

"Create a follow-up call task for lead #12345, deadline tomorrow at 10:00 AM. Then list all my incomplete tasks."

New client onboarding:

"Create a contact 'Ivan Petrov' with phone +79001234567, then create a company 'Petrov Solutions' and a lead 'Website Development' for 150,000 RUB in the main pipeline."

OAuth 2.0 Set

... View full README on GitHub