eurodns-mcp

这是一个独立的开源项目，与 EuroDNS 无关，也未获得其认可或支持。“EuroDNS”仅用于标识此服务所连接的 API。

由专业工程师在 AI 辅助下编写。提交前已审查每一行代码，并由人类对其行为负责。

---

你将获得

• 通过 36 个工具全面覆盖 API — 涵盖全部 79 项 API 操作；每组列表/获取操作、配置文件创建/更新操作、开关操作以及各产品读取操作均合并为一个工具；启用账单和不可逆操作后，共有 55 个工具。
• 为读取这些信息的模型详细描述每个工具及其参数：工具的功能和返回内容、何时优先选用相关工具以及何时不应选用、注释无法表达的行为，以及 ID 的来源。测试会检查整个工具集是否符合这些描述，工作流还会运行各注册表自带的检查器。
• 三个 DNS 工作流工具，让记录编辑更安全，因为保存区域会替换整个区域。
• 防护措施，使部署能够拒绝会花费金钱或造成破坏的操作。
• 四个提示词，覆盖值得命名的工作流；还有两个资源：可浏览的资产组合，以及说明此部署允许哪些操作的资源 — 包括解释为何预期中的工具未列入清单。
• 两种传输方式 — 本地客户端使用 stdio，共享部署使用可流式传输的 HTTP。
• 单个端点支持两个协议时代 — 原生支持 2026-07-28 版本，同时也兼容 2025 年版本的客户端；如今大多数客户端仍属于后者。
• HTTP 支持 OAuth 2.1 或共享令牌，并为每次调用记录一条审计日志。
• 可查询的历史记录 — 可询问服务已执行哪些操作，以及由谁执行。
• 1Password Connect 可作为其读取的任意机密的可选来源。

工作原理

flowchart TD
    client(["MCP client"])

    client -->|stdio| registry
    client -->|streamable HTTP| origin

    subgraph http ["HTTP transport only"]
        origin["Origin check"] --> bearer["Bearer token<br/>OAuth 2.1 or shared secret"]
        bearer --> scopes["Scope gate"]
    end

    scopes --> registry["Tool registry"]
    registry --> guard{"Guardrails<br/>read-only, billing, destructive"}
    guard -->|refused| deny["Error naming the setting to change"]
    guard -->|allowed| api[("EuroDNS User API")]

    op[("1Password Connect")] -.->|"op:// refs, at startup"| creds["Credentials"]
    creds -.-> api

    registry -.-> log[("Audit log")]
    guard -.-> log
    log -.->|eurodns_audit_query| client

这张图中有两点值得注意。授权有两个彼此独立的关卡 — 先由部署决定允许哪些操作，再由调用方的作用域决定在此范围内允许哪些操作。审计日志会记录所有路径，包括拒绝的请求，因为上游 API 使用一个共享密钥对所有调用方进行身份验证，无法自行判断调用者是谁。

要求

• Node.js 22 或更高版本。Node 20 已于 2026 年 4 月 30 日结束生命周期，不再接收安全补丁；容器镜像运行的是当前活跃的 LTS 版本 Node 24。
• EuroDNS API 凭据：Application ID 和 API key，在 EuroDNS 控制面板的 API access 页面创建。
• 运行此服务的机器的公网 IP 必须加入允许列表，同样在该控制面板中设置。API 返回 403 时，几乎总是因为缺少允许列表条目，而不是凭据错误。

快速开始

对于会自行启动服务的客户端，例如 Claude Desktop：

{
  "mcpServers": {
    "eurodns": {
      "command": "npx",
      "args": ["-y", "@jigsawfr/eurodns-mcp"],
      "env": {
        "EURODNS_APP_ID": "your-application-id",
        "EURODNS_API_KEY": "your-api-key"
      }
    }
  }
}

先在终端中试用：

npx -y @jigsawfr/eurodns-mcp

即使没有凭据，服务仍会启动，列出所有工具、提示词和资源，并在每次调用时拒绝请求，同时指出两个变量的名称——因此，市场或 npx @modelcontextprotocol/inspector 可以在你获取密钥前查看其功能。

此软件包提供两个命令：用于 stdio 的 eurodns-mcp，即上文使用的命令；以及用于 HTTP 传输的 eurodns-mcp-http，可通过 npx -p @jigsawfr/eurodns-mcp eurodns-mcp-http 访问。

如需通过 HTTP 进行共享部署，请改用容器——参见部署。

尽量不要将 API key 放入客户端配置文件中：密钥介绍了两种解决方法。

可以询问它什么

询问	对应的工具
“example.com 有哪些 DNS 记录？”	eurodns_dns_get_zone
“在 example.com 上添加 TXT 记录 _acme-challenge”	eurodns_dns_upsert_record
“如果将 www 指向 203.0.113.10，会有哪些变化？”	eurodns_dns_diff_zone
“example.lu 是否可用？”	eurodns_domain_check_availability
“我的哪些域名启用了 DNSSEC？”	eurodns_domain_get
“这个 SSL 证书何时过期？”	eurodns_subscription_get
“我的预付余额是多少？”	eurodns_account_get_prepaid_balance
“我上周更改了什么？”	eurodns_audit_query
“哪些操作被拒绝了，原因是什么？”	eurodns_audit_query

文档

页面	内容说明
工具	全部 55 个工具、整合的操作、提示词和资源
防护措施	风险类别、部署可禁止的操作，以及调用前的确认
配置	所有环境变量及其默认值
HTTP 传输	为多个客户端提供服务、静态令牌、OAuth 2.1 和作用域
密钥	避免将 API key 放入客户端配置，以及 1Password Connect
审计日志	记录内容、哈希链，以及向服务询问发生了什么
Entra ID	使用 Microsoft Entra ID 配置 OAuth 的分步指南及其注意事项
部署	容器、Fly.io、Render、Railway，以及将日志发送到 SIEM
协议	支持哪些 MCP 修订版本，以及如何在同一端点提供这两种版本
开发	构建、测试、生成的工具功能面，以及发布流程

部署

cp .env.example .env    # credentials, plus a token: openssl rand -hex 32
docker compose up -d
curl localhost:3000/healthz

已发布的镜像位于 ghcr.io/jigsawfr/eurodns-mcp，支持 linux/amd64 和 linux/arm64，并附有构建来源证明。

有两个因素决定了服务的运行位置，而且都不是通常所说的延迟或价格：

• EuroDNS API 会根据来源 IP 进行过滤，因此主机必须提供稳定的出口地址，最好是专用地址。与其他租户共用 IP，虽然保留了这种机制，却失去了保护作用。
• 历史查询工具会读取文件，因此主机需要持久化磁盘。这就排除了使用临时文件系统的平台。

综合这两点，Fly.io 更胜一筹：专用 IPv4 每月只需几美元，而其他平台则大约需要 $100。deploy/ 提供各个平台的详细信息、现成的 fly.toml 和 render.yaml，以及完整的比较。

有一项设置总会让人措手不及：在容器内，服务会监听 0.0.0.0，并且没有身份验证时，拒绝在非回环地址上启动。请将 EURODNS_MCP_AUTH 设为 token 或 oauth。

这两种方式该选哪一种

选择并非取决于你希望安全性有多高——两者都很安全——而是调用方是否需要各自独立的身份，而且这会产生一项你应该提前了解的成本。

token 是通过请求头传递的共享密钥。它可以在一分钟内配置完成，除了服务本身不需要其他东西，适合由一个人使用的部署。你需要放弃的是调用归属：审计日志会记录一个标签，因此能告诉你发生了破坏性调用，却无法说明是谁发起的。

oauth 为每个人提供独立凭据，通过五个作用域决定谁可以执行哪些操作，并在审计日志中记录真实身份。作用域决定调用方可以做什么；身份提供方决定谁能获得令牌，而大多数身份提供方默认允许目录中的所有人，因此这项设置属于配置的一部分，不能事后再考虑。其入门成本是拥有一个身份提供方认可的域名——使用 Microsoft Entra ID 时，这意味着域名必须在你的租户中完成验证，因为服务的公开 URL 必须同时作为 Application ID URI。像 *.fly.dev 这样的平台代理域名无法通过验证，因此在这种情况下，自己的域名不可或缺。Entra ID 会完整介绍整个流程，包括三个相关名称不一致时产生的错误，以及如何更进一步，为每个人配置_不同的_作用域，而不是所有人都使用同一组作用域。

先使用 token，以后再切换到 oauth，只需重启，不会产生任何其他成本：无需迁移数据，也不会改变工具的行为。

贡献

CONTRIBUTING.md 介绍工作流，docs/development.md 列出相关命令。拉取请求标题会依据 Conventional Commits 进行检查，因为变更日志就是根据它生成的。

许可证

MIT。

“EuroDNS”是 EuroDNS S.A. 的商标，不受该许可证涵盖。