Content
# @metarebalance/dadata-mcp
> **31 tools instead of ~4 in [official DaData MCP](https://dadata.ru/mcp/).** Full coverage of DaData API — addresses, companies, banks, phones, email, passports, cars, geocoding and 12 directories. Local installation via `npx`, without external hosting. Part of the series [Russian API MCP](https://github.com/theYahia/russian-mcp) (47 servers) by [@theYahia](https://github.com/theYahia).
[](https://www.npmjs.com/package/@metarebalance/dadata-mcp)
[](https://opensource.org/licenses/MIT)
> **[English version (README.en.md)](./README.en.md)**
## Why this, not the official MCP from DaData?
DaData has an [official MCP server](https://dadata.ru/mcp) with 4 tools. Our package covers **the entire API**:
| | Official MCP | @metarebalance/dadata-mcp |
|---------|:-----------:|:---------------------:|
| Tools | 4 | **31** |
| Resources | 0 | **2** |
| Prompts | 0 | **2** |
| Transport | Remote | **Local stdio** |
| Free | 1 | **23** |
| npm package | No | **Yes** |
## Quick Start
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"dadata": {
"command": "npx",
"args": ["-y", "@metarebalance/dadata-mcp"],
"env": {
"DADATA_API_KEY": "your-api-key",
"DADATA_SECRET_KEY": "your-secret-key"
}
}
}
}
```
### Claude Code
```bash
claude mcp add dadata -- npx -y @metarebalance/dadata-mcp
```
### VS Code / Cursor
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"dadata": {
"command": "npx",
"args": ["-y", "@metarebalance/dadata-mcp"],
"env": {
"DADATA_API_KEY": "your-api-key",
"DADATA_SECRET_KEY": "your-secret-key"
}
}
}
}
```
### Windsurf
Add to MCP Toolkit settings:
```json
{
"mcpServers": {
"dadata": {
"command": "npx",
"args": ["-y", "@metarebalance/dadata-mcp"],
"env": {
"DADATA_API_KEY": "your-api-key",
"DADATA_SECRET_KEY": "your-secret-key"
}
}
}
}
```
## Tools (31)
### Addresses (3)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `suggest_address` | Free | Address autocomplete with index, FIAS, coordinates, time zone |
| `clean_address` | 0.20 ₽ | Address standardization in 80+ fields with quality codes |
| `find_by_id_address` | Free | Address by FIAS code, KLADR or cadastral number |
### Companies (8)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `suggest_company` | Free | Search by name, INN or OGRN |
| `find_company_by_id` | Free | Company information by INN. Basic data is free; **finance and all OKVED codes** — only on the [«Maximum»](https://dadata.ru/pricing/?product=suggestions) tariff |
| `find_affiliated` | **Maximum** | Affiliated companies by INN. **Does not work on the free tariff** |
| `find_company_by_email` | 7 ₽ | Company by corporate email or domain |
| `find_brand` | 7 ₽ | Brand, website and logo by INN |
| `find_self_employed` | Free | Self-employed verification by INN (via Federal Taxation Service) |
| `suggest_company_by` | Free | Belarusian companies by name or UNP |
| `suggest_company_kz` | Free | Kazakhstani companies by name or BIN |
### Banks (1)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `find_bank` | Free | Search by BIK, SWIFT, INN, registration number or name |
### Full Names (2)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `suggest_fio` | Free | Full name autocomplete with gender determination |
| `clean_name` | 0.20 ₽ | Full name parsing, gender determination, declension by cases |
### Contacts (3)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `clean_phone` | 0.20 ₽ | Phone verification: operator, region, time zone |
| `clean_email` | 0.20 ₽ | Email verification: typo correction, one-time/corporate/personal |
| `suggest_email` | Free | Email autocomplete with domain suggestions |
### Passports (3)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `clean_passport` | 0.20 ₽ | Verification by the register of invalid passports of the Ministry of Internal Affairs |
| `find_fms_unit` | Free | Issuing authority by division code |
| `find_inn_by_passport` | Free | INN by passport data and date of birth (via Federal Taxation Service) |
### Cars (2)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `clean_vehicle` | 0.20 ₽ | Brand and model recognition from a string |
| `suggest_car_brand` | Free | Car brand autocomplete |
### Geolocation (2)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `geolocate_address` | Free | Reverse geocoding: address by coordinates |
| `ip_locate` | Free | City by IP address |
### Mail and Countries (2)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `find_postal_unit` | Free | Post office by index or coordinates |
| `suggest_country` | Free | Country directory (ISO 3166) |
### Logistics (1)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `find_delivery_city` | Free | City ID in SDEK, Boxberry, DPD by KLADR code |
### Composite Verification (1)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `clean_person` | 0.20 ₽ | Record verification about a person in one request: full name + address + phone + email + passport. 5-8 times cheaper than separate requests |
### Directories (1 tool, 12 directories)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `lookup_reference` | Free | OKVED 2, OKPD 2, OKTMO, metro stations, tax (Federal Taxation Service), customs (Federal Customs Service), courts, currencies (ISO 4217), MKTU, professions, positions, medical positions |
### Personal Account (2)
| Tool | Cost | Description |
|------------|:---------:|----------|
| `get_balance` | Free | Balance and usage statistics for the day |
| `get_versions` | Free | Directory update dates |
## Resources
- **`dadata://reference/quality-codes`** — DaData quality codes (qc, qc_geo) and reliability levels decryption
- **`dadata://reference/capabilities`** — API capabilities: free/paid functions, limits
## Prompts
- **`check_counterparty`** — Counterparty verification by INN: status, manager, finance, risk assessment
- **`validate_address`** — Step-by-step address validation with quality assessment
## Environment Variables
| Variable | Required | Description |
|------------|:----------:|----------|
| `DADATA_API_KEY` | Yes | API key — [register for free](https://dadata.ru/?ref=255717) and get in [personal account](https://dadata.ru/profile/#info) |
| `DADATA_SECRET_KEY` | No | Secret key for paid tools (`clean_*`). Without it, 23 free tools work |
## Tariffs and Limits
> Details: [dadata.ru/pricing](https://dadata.ru/pricing/?product=suggestions)
- **Free tariff:** up to **10,000 requests per day**. Enough for development and small projects.
- **«Maximum» tariff** is required for:
- `find_affiliated` — search for affiliated companies (**does not work** on the free tariff)
- `find_company_by_id` — full data (finance, all OKVED codes come **only** on «Maximum»; basic information is available for free)
- Paid tools (`clean_*`) — from 0.20 ₽ per request, require `DADATA_SECRET_KEY`
## Request Examples
```
Find the company by INN 7707083893
```
```
Standardize the address: msk sukhoonskaya 11 sq 89
```
```
Check the counterparty with INN 7736207543 — the company is active?
```
```
What city is there for IP 46.226.227.20?
```
```
Find the BIK and correspondent account of Sberbank
```
```
Check the passport 4510 235857 — is it in the register of invalid ones?
```
```
Find OKVED for «software development»
```
## Security
- API keys are never logged and do not fall into error responses
- All input data is validated through Zod schemes
- Protection against path traversal when building endpoints
- Hard timeout of 10 seconds for all HTTP requests
- Repeated attempts with exponential backoff only for temporary errors (429, 5xx)
- `stdout` is reserved for JSON-RPC — logs go to `stderr`
## Development
```bash
git clone https://github.com/theYahia/dadata-mcp.git
cd dadata-mcp
npm install
npm run build
npm test
```
### Test via MCP Inspector
```bash
DADATA_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
```
An interactive UI will open at `http://localhost:6274` for tool invocation and JSON-RPC message inspection.
## Part of the Russian API MCP Series
This server is part of the open series of MCP servers for Russian APIs:
| MCP | Status | Description |
|-----|--------|----------|
| [@metarebalance/dadata-mcp](https://github.com/theYahia/dadata-mcp) | ✅ ready | Addresses, companies, banks, phones |
| @theyahia/cbr-mcp | 📅 soon | Exchange rates, key rate |
| @theyahia/yookassa-mcp | 📅 soon | Payments, refunds, checks 54-FZ |
| @theyahia/moysklad-mcp | 📅 soon | Warehouse, orders, counterparties |
| @theyahia/cdek-mcp | 📅 soon | Calculation, creation, tracking |
| @theyahia/ozon-mcp | 📅 soon | Products, prices, analytics |
| @theyahia/amocrm-mcp | 📅 soon | Deals, contacts, funnels |
| ... | 📅 | **+43 servers** — full list on the showcase |
**50 MCP servers for Russian APIs:** [github.com/theYahia/russian-mcp](https://github.com/theYahia/russian-mcp)
## License
MIT
