内容
# 号码查询 API
丹麦电话号码查询、来电显示和垃圾/信任信号的公共 **合作伙伴 API** 和 **MCP 服务器**。
<!-- mcp-name: io.github.andrey-tut/nummeropslag -->
识别丹麦号码的来电者：来自官方 **CVR** 注册的公司，**电信运营商**，号码类型和基于匿名用户报告的 **垃圾/信任判决**。由官方开放数据驱动 - 不刮取。可从任何 HTTP 客户端使用，或将 **[MCP 服务器](#mcp-server-ai-agents-)** 直接插入 Claude 和其他 AI 代理。
> 🌐 服务：**[nummeropslag.dk](https://nummeropslag.dk)** · 🔑 获取密钥：**[/api-noegle](https://nummeropslag.dk/api-noegle)** · 📖 API 参考：**[Redoc](https://andrey-tut.github.io/nummeropslag-api/)** · 🧪 实时沙盒：**[/api-reference](https://nummeropslag.dk/api-reference)** · 🤖 [MCP](#mcp-server-ai-agents-)
>
> 本仓库仅包含 **公共 API 文档、OpenAPI 规范、客户端示例和 MCP 服务器**。后端源码为私有。
---
## 身份验证
所有端点都需要 API 密钥，在 `X-API-Key` 头部发送：
```http
X-API-Key: npk_your_key_here
```
每个密钥都有一个 **计划**，一组 **作用域** (`lookup`、`spam`、`operator`) 和一个 **请求配额**。随时通过 `GET /api/v1/partner/me` 检查密钥状态。
基准 URL：`https://nummeropslag.dk/api/v1`
---
## 端点
| 方法 | 端点 | 作用域 | 描述 |
|---|---|---|---|
| GET | `/partner/lookup/{e164}` | `lookup` | 完整查询 - 运营商、CVR 公司、垃圾/信任信号 |
| GET | `/partner/spam/{e164}` | `spam` | 紧凑的垃圾/信任判决 |
| GET | `/partner/operator/{e164}` | `operator` | 电信运营商 + 号码类型 |
| GET | `/partner/search?q=` | `lookup` | 按名称搜索公司（CVR） |
| GET | `/partner/me` | — | 您的密钥状态：计划、作用域、配额/用量 |
`{e164}` 接受 8 位数字的丹麦号码或完整的 E.164 - 例如 `33633363` 或 `+4533633363`。
完整的机器可读合约：[`openapi/openapi.yaml`](openapi/openapi.yaml) · [`openapi/openapi.json`](openapi/openapi.json)。
---
## 快速入门
```bash
export NUMMEROPSLAG_API_KEY=npk_your_key_here
curl -H "X-API-Key: $NUMMEROPSLAG_API_KEY" \
https://nummeropslag.dk/api/v1/partner/spam/33633363
```
## 客户端示例
在 [`examples/`](examples/) 中准备好运行、无依赖的客户端：
| 语言 | 文件 | 运行 |
|---|---|---|
| Bash / curl | [`examples/curl.sh`](examples/curl.sh) | `./curl.sh 33633363` |
| Python (stdlib) | [`examples/python_client.py`](examples/python_client.py) | `python3 python_client.py 33633363` |
| Node.js 18+ | [`examples/node_client.js`](examples/node_client.js) | `node node_client.js 33633363` |
| PHP | [`examples/php_client.php`](examples/php_client.php) | `php php_client.php 33633363` |
所有客户端都从 `NUMMEROPSLAG_API_KEY` 环境变量中读取密钥。
---
## 工作流集成
在流行的自动化和 AI 工作流构建器中使用 Nummeropslag 作为原生节点和工具：
| 平台 | 集成 | 位置 |
|---|---|---|
| n8n | 具有五个操作和 AI 工具支持的社区节点 | [`integrations/n8n`](integrations/n8n) |
| Dify | 工作流、聊天流和代理的可安装工具插件 | [`integrations/dify`](integrations/dify) |
| Langflow | 具有工具模式支持的自定义组件 | [`integrations/langflow`](integrations/langflow) |
| Flowise | 即插即用的自定义工具函数和模式 | [`integrations/flowise`](integrations/flowise) |
集成将 API 密钥存储在每个平台的凭证/秘密系统中，并仅向 `https://nummeropslag.dk` 发送查询。
---
## MCP 服务器（AI 代理） 🤖
为您的 AI 代理（Claude Desktop、Claude Code 或任何 **模型上下文协议** 客户端）提供直接访问丹麦电话号码数据的功能。[`mcp/`](mcp/) 中的服务器封装了合作伙伴 API 作为 MCP 工具 - 相同官方数据，相同隐私规则（不显示私人个人的姓名）。
### 一键桌面安装
从 [GitHub Releases](https://github.com/andrey-tut/nummeropslag-api/releases) 下载最新的 `nummeropslag-mcp-*.mcpb` 包，用兼容的桌面客户端打开，并提示输入 Nummeropslag API 密钥。包使用托管的 `uv` 运行时，因此用户无需手动安装 Python 依赖项。
规范的注册表标识符为 `io.github.andrey-tut/nummeropslag`。
### Docker
相同的_stdio_服务器作为公共 OCI 镜像发布：
```bash
docker run --rm -i \
-e NUMMEROPSLAG_API_KEY=npk_your_key_here \
ghcr.io/andrey-tut/nummeropslag-mcp:latest
```
MCP 调用针对 **单独的 MCP 配额**（不是您的 REST 配额）进行计量；服务器自动发送 `X-Client: mcp`。
**工具**
| 工具 | 描述 |
|---|---|
| `lookup_number(number)` | 完整记录：公司（CVR）、运营商、垃圾/信任、评论 |
| `check_spam(number)` | 紧凑的垃圾/骗局判决（来电显示样式） |
| `get_operator(number)` | 仅运营商 + 号码类型（最便宜） |
| `search_businesses(query, limit)` | 按名称查找丹麦公司（CVR） |
| `api_status()` | 您的密钥的作用域 + 配额使用情况 |
**设置 - 通过 PyPI（推荐）**
```bash
pip install nummeropslag-mcp # 或：uvx nummeropslag-mcp
export NUMMEROPSLAG_API_KEY=npk_your_key_here # https://nummeropslag.dk/api-noegle
nummeropslag-mcp # stdio 传输
```
**添加到 Claude Desktop** (`claude_desktop_config.json`) **或 Claude Code** (`.mcp.json`)：
```json
{
"mcpServers": {
"nummeropslag": {
"command": "nummeropslag-mcp",
"env": { "NUMMEROPSLAG_API_KEY": "npk_your_key_here" }
}
}
}
```
<details><summary>从源代码运行（无 PyPI）</summary>
```bash
pip install "mcp[cli]" httpx
python mcp/server.py
```
…and 在上面的配置中使用 `"command": "python", "args": ["/absolute/path/to/nummeropslag-api/mcp/server.py"]`。
</details>
重启您的客户端，然后询问例如 *" +45 70 10 20 30 是垃圾邮件吗?"* 或 *"谁拥有 33 63 33 63?"*。
---
## 错误
错误使用一致的信封：
```json
{ "error": { "code": "forbidden", "message": "…", "details": {} } }
```
常见代码：`unauthorized`（缺少/无效密钥），`forbidden`（不允许范围），`rate_limited`（超出配额），`not_found`。
## 数据和隐私
- 核心数据：官方 **CVR**（公司 + 生产单位）和丹麦 **号码计划**（SDFI，CC0）。
- 垃圾邮件判决使用 **k-匿名性** - 公共“垃圾邮件”标签需要多个独立报告。
- **私人个人的姓名永远不会被暴露。** 联系方式从未上传（GDPR 合规）。
## 隐私政策
MCP 服务器仅将用户请求的电话号码或业务查询发送到第一方 Nummeropslag API。它不读取对话、文件、联系人或通话记录。有关数据收集、使用、保留、共享和联系信息的完整 [Nummeropslag 隐私政策](https://nummeropslag.dk/privatlivspolitik)，请参见。
## 许可证
本仓库中的客户端示例和 OpenAPI 规范在 **MIT 许可证**下发布（参见 [LICENSE](LICENSE)）- 自由复制和修改。Nummeropslag API 服务本身及其数据为专有；使用受 [nummeropslag.dk](https://nummeropslag.dk) 条款管辖。
