# MCP-сервер для DaData — подсказки адресов, проверка компаний по ИНН и очистка данных через ИИ

Если вы искали, как подключить DaData к нейросети, пробить контрагента по ИНН, разобрать адрес на составные части или почистить базу телефонов и email — это оно. **31 инструмент вместо ~4 у [официального DaData MCP](https://dadata.ru/mcp/)**: адреса, компании, банки, телефоны, паспорта, автомобили, геокодирование и 12 справочников, из них 23 метода бесплатны. Ставится локально через `npx`, без внешнего хостинга — ключ остаётся у вас. Часть серии [WWmcp](https://github.com/theYahia/WWmcp) (46 серверов) by [@theYahia](https://github.com/theYahia).

[![npm](https://img.shields.io/npm/v/@metarebalance/dadata-mcp)](https://www.npmjs.com/package/@metarebalance/dadata-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **[English version (README.en.md)](./README.en.md)**

## Почему этот, а не официальный MCP от DaData?

У DaData есть [официальный MCP-сервер](https://dadata.ru/mcp) с 4 инструментами. Наш пакет покрывает **весь API**:

| | Официальный MCP | @metarebalance/dadata-mcp |
|---------|:-----------:|:---------------------:|
| Инструменты | 4 | **31** |
| Ресурсы | 0 | **2** |
| Промпты | 0 | **2** |
| Транспорт | Удалённый | **Локальный stdio** |
| Бесплатные | 1 | **23** |
| npm-пакет | Нет | **Да** |

## Быстрый старт

### Claude Desktop

Добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "dadata": {
      "command": "npx",
      "args": ["-y", "@metarebalance/dadata-mcp"],
      "env": {
        "DADATA_API_KEY": "ваш-api-ключ",
        "DADATA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add dadata -- npx -y @metarebalance/dadata-mcp
```

### VS Code / Cursor

Добавьте в `.vscode/mcp.json`:

```json
{
  "servers": {
    "dadata": {
      "command": "npx",
      "args": ["-y", "@metarebalance/dadata-mcp"],
      "env": {
        "DADATA_API_KEY": "ваш-api-ключ",
        "DADATA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}
```

### Windsurf

Добавьте в настройки MCP Toolkit:

```json
{
  "mcpServers": {
    "dadata": {
      "command": "npx",
      "args": ["-y", "@metarebalance/dadata-mcp"],
      "env": {
        "DADATA_API_KEY": "ваш-api-ключ",
        "DADATA_SECRET_KEY": "ваш-секретный-ключ"
      }
    }
  }
}
```

## Инструменты (31)

### Адреса (3)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `suggest_address` | Бесплатно | Автодополнение адресов с индексом, ФИАС, координатами, часовым поясом |
| `clean_address` | 0.20 ₽ | Стандартизация адреса в 80+ полей с кодами качества |
| `find_by_id_address` | Бесплатно | Адрес по коду ФИАС, КЛАДР или кадастровому номеру |

### Компании (8)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `suggest_company` | Бесплатно | Поиск по названию, ИНН или ОГРН |
| `find_company_by_id` | Бесплатно | Информация о компании по ИНН. Базовые данные бесплатно; **финансы и все коды ОКВЭД** — только тариф [«Максимальный»](https://dadata.ru/pricing/?product=suggestions) |
| `find_affiliated` | **Максимальный** | Аффилированные компании по ИНН. **Не работает на бесплатном тарифе** |
| `find_company_by_email` | 7 ₽ | Компания по корпоративному email или домену |
| `find_brand` | 7 ₽ | Бренд, сайт и логотип по ИНН |
| `find_self_employed` | Бесплатно | Проверка самозанятого по ИНН (через ФНС) |
| `suggest_company_by` | Бесплатно | Компании Беларуси по названию или УНП |
| `suggest_company_kz` | Бесплатно | Компании Казахстана по названию или БИН |

### Банки (1)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `find_bank` | Бесплатно | Поиск по БИК, SWIFT, ИНН, рег. номеру или названию |

### ФИО (2)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `suggest_fio` | Бесплатно | Автодополнение ФИО с определением пола |
| `clean_name` | 0.20 ₽ | Разбор ФИО, определение пола, склонение по падежам |

### Контакты (3)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `clean_phone` | 0.20 ₽ | Проверка телефона: оператор, регион, часовой пояс |
| `clean_email` | 0.20 ₽ | Проверка email: исправление опечаток, одноразовый/корпоративный/личный |
| `suggest_email` | Бесплатно | Автодополнение email с подсказкой доменов |

### Паспорта (3)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `clean_passport` | 0.20 ₽ | Проверка по реестру недействительных паспортов МВД |
| `find_fms_unit` | Бесплатно | Кем выдан паспорт по коду подразделения |
| `find_inn_by_passport` | Бесплатно | ИНН по паспортным данным и дате рождения (через ФНС) |

### Автомобили (2)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `clean_vehicle` | 0.20 ₽ | Распознавание марки и модели из строки |
| `suggest_car_brand` | Бесплатно | Автодополнение марок автомобилей |

### Геолокация (2)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `geolocate_address` | Бесплатно | Обратное геокодирование: адрес по координатам |
| `ip_locate` | Бесплатно | Город по IP-адресу |

### Почта и страны (2)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `find_postal_unit` | Бесплатно | Почтовое отделение по индексу или координатам |
| `suggest_country` | Бесплатно | Справочник стран (ISO 3166) |

### Логистика (1)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `find_delivery_city` | Бесплатно | ID города в СДЭК, Boxberry, DPD по коду КЛАДР |

### Композитная проверка (1)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `clean_person` | 0.20 ₽ | Проверка записи о человеке одним запросом: ФИО + адрес + телефон + email + паспорт. В 5-8 раз дешевле раздельных запросов |

### Справочники (1 инструмент, 12 справочников)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `lookup_reference` | Бесплатно | ОКВЭД 2, ОКПД 2, ОКТМО, станции метро, налоговые (ФНС), таможни (ФТС), суды, валюты (ISO 4217), МКТУ, профессии, должности, медицинские должности |

### Личный кабинет (2)

| Инструмент | Стоимость | Описание |
|------------|:---------:|----------|
| `get_balance` | Бесплатно | Баланс и статистика использования за день |
| `get_versions` | Бесплатно | Даты обновления справочников |

## Ресурсы

- **`dadata://reference/quality-codes`** — Расшифровка кодов качества DaData (qc, qc_geo) и уровней достоверности
- **`dadata://reference/capabilities`** — Возможности API: бесплатные/платные функции, лимиты

## Промпты

- **`check_counterparty`** — Проверка контрагента по ИНН: статус, руководитель, финансы, оценка риска
- **`validate_address`** — Пошаговая валидация адреса с оценкой качества

## Переменные окружения

| Переменная | Обязательна | Описание |
|------------|:----------:|----------|
| `DADATA_API_KEY` | Да | API-ключ — [зарегистрируйтесь бесплатно](https://dadata.ru/?ref=255717) и получите в [личном кабинете](https://dadata.ru/profile/#info) |
| `DADATA_SECRET_KEY` | Нет | Секретный ключ для платных инструментов (`clean_*`). Без него работают 23 бесплатных |

## Тарифы и лимиты

> Подробнее: [dadata.ru/pricing](https://dadata.ru/pricing/?product=suggestions)

- **Бесплатный тариф:** до **10 000 запросов в сутки**. Достаточно для разработки и небольших проектов.
- **Тариф «Максимальный»** необходим для:
  - `find_affiliated` — поиск аффилированных компаний (**не работает** на бесплатном тарифе)
  - `find_company_by_id` — полные данные (финансы, все коды ОКВЭД приходят **только** на «Максимальном»; базовая информация доступна бесплатно)
- Платные инструменты (`clean_*`) — от 0.20 ₽ за запрос, требуют `DADATA_SECRET_KEY`

## Примеры запросов

```
Найди компанию по ИНН 7707083893
```

```
Стандартизируй адрес: мск сухонская 11 кв 89
```

```
Проверь контрагента с ИНН 7736207543 — компания действует?
```

```
Какой город у IP 46.226.227.20?
```

```
Найди БИК и корсчёт Сбербанка
```

```
Проверь паспорт 4510 235857 — есть в реестре недействительных?
```

```
Найди ОКВЭД для «разработка программного обеспечения»
```

## Безопасность

- API-ключи никогда не логируются и не попадают в ответы об ошибках
- Все входные данные валидируются через Zod-схемы
- Защита от path traversal при построении эндпоинтов
- Жёсткий таймаут 10 секунд на все HTTP-запросы
- Повторные попытки с экспоненциальным backoff только на временные ошибки (429, 5xx)
- `stdout` зарезервирован для JSON-RPC — логи идут в `stderr`

## Разработка

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

### Тест через MCP Inspector

```bash
DADATA_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```

Откроется интерактивный UI на `http://localhost:6274` для вызова инструментов и просмотра JSON-RPC сообщений.

## Часть серии WWmcp

Этот сервер — часть открытой серии MCP-серверов для российских API:

| MCP | Статус | Описание |
|-----|--------|----------|
| [@metarebalance/dadata-mcp](https://github.com/theYahia/dadata-mcp) | ✅ готов | Адреса, компании, банки, телефоны |
| @theyahia/cbr-mcp | 📅 скоро | Курсы валют, ключевая ставка |
| @theyahia/yookassa-mcp | 📅 скоро | Платежи, возвраты, чеки 54-ФЗ |
| @theyahia/moysklad-mcp | 📅 скоро | Склад, заказы, контрагенты |
| @theyahia/cdek-mcp | 📅 скоро | Расчёт, создание, трекинг |
| @theyahia/ozon-mcp | 📅 скоро | Товары, цены, аналитика |
| @theyahia/amocrm-mcp | 📅 скоро | Сделки, контакты, воронки |
| ... | 📅 | **46 серверов** — полный список на витрине |

**46 MCP-серверов для российских API:** [github.com/theYahia/WWmcp](https://github.com/theYahia/WWmcp)

## Лицензия

MIT

---

Часть [WWmcp](https://github.com/theYahia/WWmcp) · Telegram: [@vhodvai](https://t.me/vhodvai)