内容
# @metarebalance/dadata-mcp
> **31 工具代替官方 DaData MCP 的 ~4 工具.** 完整覆盖 DaData API — 地址、公司、银行、电话、邮箱、护照、汽车、地理编码和 12 个参考手册。 通过 `npx` 进行本地安装，无需外部托管。 [俄罗斯 API MCP](https://github.com/theYahia/russian-mcp) 系列的一部分（47 个服务器） by [@theYahia](https://github.com/theYahia).
[](https://www.npmjs.com/package/@metarebalance/dadata-mcp)
[](https://opensource.org/licenses/MIT)
> **[English 版本 (README.en.md)](./README.en.md)**
## 为什么选择这个，而不是 DaData 官方 MCP？
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` | 免费 | 地址自动补全，含索引、FIAS、坐标、时区 |
| `clean_address` | 0.20 ₽ | 地址标准化为 80+ 个字段，含质量代码 |
| `find_by_id_address` | 免费 | 根据 FIAS 代码、CLADR 或 cadastral 编号查找地址 |
### 公司（8）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `suggest_company` | 免费 | 根据名称、INN 或 OGRN 搜索 |
| `find_company_by_id` | 免费 | 根据 INN 查找公司信息。基本数据免费；**财务和所有 OKVED 代码** — 仅限 [“最大”](https://dadata.ru/pricing/?product=suggestions) 套餐 |
| `find_affiliated` | **最大** | 根据 INN 查找关联公司。**免费套餐不可用** |
| `find_company_by_email` | 7 ₽ | 根据公司邮箱或域名查找公司 |
| `find_brand` | 7 ₽ | 根据 INN 查找品牌、网站和徽标 |
| `find_self_employed` | 免费 | 根据 INN（通过联邦税务局）检查自雇人士 |
| `suggest_company_by` | 免费 | 根据名称或 UPN 查找白俄罗斯公司 |
| `suggest_company_kz` | 免费 | 根据名称或 BIN 查找哈萨克斯坦公司 |
### 银行（1）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `find_bank` | 免费 | 根据 BIK、SWIFT、INN、注册编号或名称搜索 |
### 姓名（2）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `suggest_fio` | 免费 | 姓名自动补全，含性别判定 |
| `clean_name` | 0.20 ₽ | 姓名解析，性别判定，格变化 |
### 联系方式（3）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `clean_phone` | 0.20 ₽ | 电话检查：运营商、地区、时区 |
| `clean_email` | 0.20 ₽ | 邮箱检查：纠正拼写错误、一次性/公司/个人邮箱 |
| `suggest_email` | 免费 | 邮箱自动补全，提示域名 |
### 护照（3）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `clean_passport` | 0.20 ₽ | 通过内务部无效护照登记册检查 |
| `find_fms_unit` | 免费 | 根据分区代码查找护照颁发单位 |
| `find_inn_by_passport` | 免费 | 根据护照信息和出生日期（通过联邦税务局）查找 INN |
### 汽车（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` | 免费 | 根据 CLADR 代码查找城市 ID（СДЭК, Boxberry, DPD） |
### 综合检查（1）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `clean_person` | 0.20 ₽ | 单个请求检查人员记录：姓名 + 地址 + 电话 + 邮箱 + 护照。比单独请求便宜 5-8 倍 |
### 参考手册（1 个工具，12 个参考手册）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `lookup_reference` | 免费 | OKVED 2, OKPD 2, OКТМО, 地铁站, 税务（ФНС）, 海关（ФТС）, 法院, 货币（ISO 4217）, МКТУ, 职业, 职位, 医疗职位 |
### 个人账户（2）
| 工具 | 费用 | 描述 |
|------------|:---------:|----------|
| `get_balance` | 免费 | 当日余额和使用情况统计 |
| `get_versions` | 免费 | 参考手册更新日期 |
## 资源
- **`dadata://reference/quality-codes`** — DaData 质量代码（qc, qc_geo）和可靠性级别解释
- **`dadata://reference/capabilities`** — API 功能：免费/付费功能，限制
## 提示
- **`check_counterparty`** — 根据 INN 检查交易对手：状态、负责人、财务、风险评估
- **`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` — 完整数据（财务，所有 OKVED 代码仅在“最大”资费中提供；基本信息免费）
- 付费工具（`clean_*`）— 从 0.20 ₽ 每请求，需 `DADATA_SECRET_KEY`
## 请求示例
```
查找 INN 为 7707083893 的公司
```
```
标准化地址：莫斯科，苏霍诺夫斯卡亚，11 号，89 号房间
```
```
检查 INN 为 7736207543 的交易对手 — 公司是否有效？
```
```
IP地址 46.226.227.20 的城市是什么？
```
```
查找 Sberbank 的 BIK 和对应账户
```
```
检查护照 4510 235857 — 是否在无效护照登记册中？
```
```
查找“软件开发”的 OKVED 代码
```
## 安全
- API 密钥从不记录在日志中，也不会出现在错误响应中
- 所有输入数据都通过 Zod 模式验证
- 构建端点时防止路径遍历
- 所有 HTTP 请求的超时时间为 10 秒
- 仅针对临时错误（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 消息。
## 俄罗斯 API MCP 系列的一部分
该服务器是为俄罗斯 API 提供的开放式 MCP 服务器系列的一部分：
| MCP | 状态 | 描述 |
|-----|--------|----------|
| [@metarebalance/dadata-mcp](https://github.com/theYahia/dadata-mcp) | ✅ 已准备 | 地址、公司、银行、电话 |
| @theyahia/cbr-mcp | 📅 即将推出 | 汇率，关键利率 |
| @theyahia/yookassa-mcp | 📅 即将推出 | 支付、退款、收据 54-FZ |
| @theyahia/moysklad-mcp | 📅 即将推出 | 仓库、订单、交易对手 |
| @theyahia/cdek-mcp | 📅 即将推出 | 计算、创建、跟踪 |
| @theyahia/ozon-mcp | 📅 即将推出 | 商品、价格、分析 |
| @theyahia/amocrm-mcp | 📅 即将推出 | 交易、联系人、漏斗 |
| ... | 📅 | **+43 服务器** — 完整列表在展厅中 |
**50 个俄罗斯 API 的 MCP 服务器：** [github.com/theYahia/russian-mcp](https://github.com/theYahia/russian-mcp)
## 许可证
MIT
