npm package: @metarebalance/dadata-mcp
Description: Full-featured MCP server for DaData.ru — Russian address validation, company lookup, phone cleaning, geocoding for AI agents
Author: metarebalance
Latest version: 1.0.6

# @metarebalance/dadata-mcp

> **31 инструмент вместо ~4 у [официального DaData MCP](https://dadata.ru/mcp/).** Полное покрытие DaData API — адреса, компании, банки, телефоны, email, паспорта, автомобили, геокодирование и 12 справочников. Локальная установка через `npx`, без внешнего хостинга. Часть серии [Russian API MCP](https://github.com/theYahia/russian-mcp) (50 серверов) 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` | Бесплатно | Полная информация: руководитель, учредители, финансы, ОКВЭД |
| `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-ключ из [dadata.ru/profile](https://dadata.ru/profile/#info) |
| `DADATA_SECRET_KEY` | Нет | Секретный ключ для платных инструментов (`clean_*`). Без него работают 23 бесплатных |

## Примеры запросов

```
Найди компанию по ИНН 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 сообщений.

## Часть серии Russian API MCP

Этот сервер — часть открытой серии 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 | 📅 скоро | Сделки, контакты, воронки |
| ... | 📅 | **+43 сервера** — полный список на витрине |

**50 MCP-серверов для российских API:** [github.com/theYahia/russian-mcp](https://github.com/theYahia/russian-mcp)

## Лицензия

MIT