@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).
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. |
| 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
