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

1. Go to your amoCRM account settings: https://YOUR_SUBDOMAIN.amocrm.ru/settings/widgets/
2. Create a new integration (external integration)
3. Set the redirect URI to https://YOUR_SUBDOMAIN.amocrm.ru
4. Copy the Client ID and Client Secret
5. Authorize the integration to get the initial Authorization Code
6. 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"
  }'

7. Save the access_token and refresh_token from the response
8. 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