@theyahia/amocrm-mcp

Name: amocrm mcp
Author: theyahia

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 Setup Guide

Go to your amoCRM account settings: https://YOUR_SUBDOMAIN.amocrm.ru/settings/widgets/
Create a new integration (external integration)
Set the redirect URI to https://YOUR_SUBDOMAIN.amocrm.ru
Copy the Client ID and Client Secret
Authorize the integration to get the initial Authorization Code
Exchange the code for tokens:

curl -X POST https://YOUR_SUBDOMAIN.amocrm.ru/oauth2/access_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "authorization_code",
    "code": "YOUR_AUTH_CODE",
    "redirect_uri": "https://YOUR_SUBDOMAIN.amocrm.ru"
  }'

Save the access_token and refresh_token from the response
The server will automatically refresh expired tokens if AMOCRM_REFRESH_TOKEN, AMOCRM_CLIENT_ID, and AMOCRM_CLIENT_SECRET are set

Error Handling

401 Unauthorized: Auto-refreshes token if refresh credentials are configured, then retries
429 Rate Limited: Respects Retry-After header, waits and retries
5xx Server Errors: Exponential backoff retry (up to 3 attempts)
Rate Limiting: Built-in 150ms delay between requests (~7 req/sec) to stay within amoCRM limits

Development

git clone https://github.com/theYahia/amocrm-mcp.git
cd amocrm-mcp
npm install
npm run build
npm test

License

MIT