@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

Related MCP server: 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

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

Tools (19)

Leads

Contacts

Companies

Pipelines

Tasks

Unsorted

Notes

Search

Events

Account

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