wdns

西部数码 DNS 解析管理 CLI & MCP 工具，基于 Bun + TypeScript 构建。

West.cn DNS management CLI & MCP server. Built with Bun + TypeScript.

基于西部数码 DNS 解析 API 文档实现。

Based on the West.cn DNS Resolution API Documentation.

功能特性 | Features

• 增删改查 — 列表、添加、修改（upsert）、删除 DNS 记录
• 多格式输出 — table、markdown、json、yaml、toml、xml
• 智能终端检测 — 终端中显示彩色表格，管道输出自动切换 markdown
• DNS 生效验证 — 变更后轮询 DNS 解析确认传播，支持 --verify
• 双路 DNS 解析 — 系统 DNS + DNS-over-HTTPS（Cloudflare、Google、AliDNS、Quad9、DNSPod）
• MCP 服务器 — 支持 AI Agent 通过 MCP stdio 协议调用
• 跨平台 — 单二进制文件（bun build --compile）或轻量 .mjs 单文件

• CRUD operations — list, add, modify (upsert), remove DNS records
• Multi-format output — table, markdown, json, yaml, toml, xml
• Smart TTY detection — colored table in terminal, markdown when piped
• DNS verification — poll DNS propagation after changes with --verify
• Dual DNS resolution — system DNS + DNS-over-HTTPS (Cloudflare, Google, AliDNS, Quad9, DNSPod)
• MCP server — stdio transport for AI agent integration
• Cross-platform — single binary via bun build --compile, or lightweight .mjs bundle

安装 | Installation

# 安装依赖 | Install dependencies
bun install

# 直接运行 | Run directly
bun run start -- list example.com

# 构建当前平台二进制 | Build single binary (current platform)
bun run build

# 构建单 JS 文件（轻量，可用 node 或 bun 运行）
# Build single JS file (lightweight, runs with node or bun)
bun run build:js

# 构建所有平台 | Build for all platforms
bun run build:all

构建目标 | Build targets

认证方式 | Authentication

支持两种认证方式：

Two authentication methods are supported:

方式一：域名 API Key（推荐）| Option 1: Domain API Key (recommended)

获取方式 | How to obtain:

1. 登录西部数码，进入 域名管理页面
2. 点击具体域名进入 DNS 解析管理页面
3. 找到「管理密码」，复制其后面的 ApiKey 值即可

1. Log in to West.cn, go to the Domain Management page
2. Click on the specific domain to enter the DNS management page
3. Find "管理密码" (Management Password) and copy the ApiKey value after it

export WEST_API_DOMAIN_KEY="your-api-domain-key"

或通过 CLI 参数传入 | Or pass via CLI:

wdns -k "your-api-domain-key" list example.com

方式二：用户名 + API 密码 | Option 2: Username + API Password

1. 登录西部数码，进入 域名管理页面
2. 点击具体域名进入 DNS 解析管理页面
3. 找到「管理密码」，复制其后面的 管理密码 值即可(很短的明文密码，不是ApiKey)

export WEST_USERNAME="your-username"
export WEST_API_PASSWORD="your-api-password"

或通过 CLI 参数传入 | Or pass via CLI:

wdns -u "your-username" -p "your-api-password" list example.com

.env 文件 | .env file

复制 .env.example 为 .env 并填入凭据：

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

# 认证（二选一）| Auth (pick one)
WEST_API_DOMAIN_KEY=your-key
# OR
WEST_USERNAME=your-username
WEST_API_PASSWORD=your-password

# MCP 模式：锁定域名 | MCP mode: lock domain
WEST_DOMAIN=example.com

CLI 使用 | CLI Usage

全局选项 | Global options

--version                  显示版本 | Show version
-u, --username <user>      西部数码账号 | West.cn account username
-p, --password <pass>      API 密码 | API password
-k, --key <key>            域名 API Key | Domain API key
-f, --format <fmt>         输出格式 | Output format (table|markdown|json|yaml|toml|xml)
--verify                   变更后验证 DNS 生效 | Verify DNS propagation after changes
--timeout <seconds>        验证最大等待时间 | Max verification wait time (default: 120)

列表查询 | List records

# 列出所有记录 | List all records
wdns list example.com

# 按主机名和类型筛选 | Filter by hostname and type
wdns list example.com -H www -t A

# JSON 格式输出 | JSON output
wdns list example.com -f json

# 按线路筛选 | Filter by route line
wdns list example.com -l telecom

# 分页查询 | Paginate
wdns list example.com --limit 50 --page 2

添加记录 | Add a record

# 添加 A 记录 | Add an A record
wdns add example.com -t A -H www -v 1.2.3.4

# 自定义 TTL | Add with custom TTL
wdns add example.com -t A -H api -v 1.2.3.4 --ttl 3600

# 添加 MX 记录 | Add MX record with priority
wdns add example.com -t MX -H @ -v mail.example.com --mx 10

# 添加 TXT 记录（SPF）| Add TXT record (SPF)
wdns add example.com -t TXT -H @ -v "v=spf1 include:_spf.google.com ~all"

# 添加 CNAME 记录 | Add CNAME record
wdns add example.com -t CNAME -H blog -v blog.otherdomain.com

# 指定线路 | Add for specific route line
wdns add example.com -t A -H www -v 1.1.1.1 -l telecom

# 添加并验证生效 | Add and verify propagation
wdns --verify add example.com -t A -H test -v 1.2.3.4

修改记录（upsert）| Modify a record (upsert)

modify 命令自动处理创建和更新 —— 记录不存在时自动创建。

The modify command handles both creation and updates — auto-creates if the record doesn't exist.

# 修改记录（不存在则创建）| Modify (creates if not exists)
wdns modify example.com -t A -H www -v 5.6.7.8

# 严格模式（不存在则报错）| Strict mode (fail if not found)
wdns modify example.com -t A -H www -v 5.6.7.8 --strict

# 通过 ID 精确修改 | Modify by record ID
wdns modify example.com -t A -H www -v 5.6.7.8 -i 12345

# 修改并验证生效 | Modify with verification
wdns --verify --timeout 60 modify example.com -t A -H www -v 5.6.7.8

删除记录 | Remove a record

必须提供 -i <id> 或同时提供 -H <host> + -t <type>。

Must provide either -i <id> or both -H <host> + -t <type>.

# 通过 ID 删除（最安全）| Remove by record ID (safest)
wdns remove example.com -i 12345

# 通过主机名+类型删除 | Remove by hostname + type
wdns remove example.com -H www -t A

# 指定线路删除 | Remove with specific route line
wdns remove example.com -H www -t A -l telecom

# 删除并验证 | Remove and verify
wdns --verify remove example.com -H www -t A -v 1.2.3.4

输出格式 | Output formats

使用 --format 时，消息输出到 stderr，结构化数据输出到 stdout：

When --format is set, messages go to stderr, structured data goes to stdout:

# 仅结构化数据 | Only structured data
wdns -f json list example.com 2>/dev/null

# 仅消息 | Only messages
wdns -f json list example.com >/dev/null

DNS 验证 | DNS Verification

--verify 在变更后轮询 DNS 解析器确认传播生效：

The --verify flag polls DNS resolvers after changes to confirm propagation:

wdns --verify --timeout 60 modify example.com -t A -H www -v 1.2.3.4

采用双路解析策略：

Dual-backup strategy:

• 系统 DNS — 通过 dns/promises 使用本地解析器 | Local resolver via dns/promises
• DNS-over-HTTPS — Cloudflare、Google、AliDNS、Quad9、DNSPod（并行查询）| Parallel queries

当系统 DNS 被劫持或污染时，自动使用 DoH 结果。验证结果中的 resolved_by 字段标识确认来源。

If system DNS is blocked or polluted, DoH results are used automatically. The resolved_by field shows which resolver confirmed.

退出码 | Exit codes:

• 0 — 成功 Success（含验证通过 verified if --verify is set）
• 1 — API 错误或认证失败 API error or auth failure
• 2 — 验证超时 Verification timeout

MCP 服务器 | MCP Server

wdns 内置 MCP（Model Context Protocol）stdio 服务器，让 AI Agent 可以直接管理 DNS 记录。

wdns includes a built-in MCP (Model Context Protocol) stdio server, enabling AI agents to manage DNS records directly.

MCP 命令 | MCP command

wdns [auth flags] mcp [-d <domain>]

域名锁定 | Domain locking:

域名 API Key 只对单个域名有效。使用 -d 锁定域名后：

Domain API Key only works for a single domain. With -d domain locking:

• MCP 工具的 domain 参数会被移除，AI 无需也无法指定域名
• 工具描述会自动标注当前管理的域名（如 List DNS records for example.com）
• 所有操作结果都会在返回数据中包含 domain 字段

• The domain parameter is removed from tool schemas, AI cannot specify a different domain
• Tool descriptions automatically indicate the managed domain (e.g., List DNS records for example.com)
• All operation results include the domain field in response data

认证传递 | Auth passthrough:

MCP 模式支持通过 CLI 全局选项传递认证信息（-k、-u、-p），也支持环境变量。

MCP mode supports passing auth via CLI global flags (-k, -u, -p), as well as environment variables.

# 通过 CLI 参数传递认证和域名 | Pass auth and domain via CLI flags
wdns -k "your-key" mcp -d example.com

# 通过环境变量 | Via environment variables
export WEST_API_DOMAIN_KEY="your-key"
export WEST_DOMAIN="example.com"
wdns mcp

环境变量 | Environment variables:

CLI 参数优先级高于环境变量。

CLI flags take precedence over environment variables.

MCP 工具 | MCP tools

详细的 CLI 使用文档请参考 docs/SKILL.md。

For detailed CLI usage documentation, see docs/SKILL.md.

在 Claude Code 中使用 | Use with Claude Code

Claude Code 是 Anthropic 官方的命令行 AI 编程工具。

Claude Code is Anthropic's official CLI AI coding tool.

安装 wdns MCP 服务器（推荐：带域名锁定）| Install wdns MCP server (recommended: with domain lock):

# 使用 -k 传递认证 + -d 锁定域名（推荐）
# Pass auth via -k + lock domain with -d (recommended)
claude mcp add wdns -- ./dist/wdns -k "your-key" mcp -d example.com

# 使用 bun 直接运行 | Or run with bun directly
claude mcp add wdns -- bun run src/index.ts -k "your-key" mcp -d example.com

# 使用 JS 单文件 | Or use the JS bundle
claude mcp add wdns -- node ./dist/wdns.mjs -k "your-key" mcp -d example.com

或使用环境变量 | Or use environment variables:

claude mcp add wdns \
  -e WEST_API_DOMAIN_KEY=your-key \
  -e WEST_DOMAIN=example.com \
  -- ./dist/wdns mcp

不锁定域名（使用账号密码，支持多域名）| Without domain lock (multi-domain with username + password):

claude mcp add wdns \
  -e WEST_USERNAME=your-username \
  -e WEST_API_PASSWORD=your-password \
  -- ./dist/wdns mcp

安装后，Claude Code 会自动发现 dns_list、dns_add、dns_modify、dns_remove 四个工具。你可以直接用自然语言让 Claude 管理 DNS，例如：

After installation, Claude Code will automatically discover the four tools. You can use natural language to manage DNS, for example:

"帮我把 www 记录改成 1.2.3.4"

"列出所有 TXT 记录"

"删除 test 这个 A 记录"

在 OpenCode 中使用 | Use with OpenCode

OpenCode 是一个开源的终端 AI 编程工具。

OpenCode is an open-source terminal AI coding tool.

配置 MCP 服务器（推荐：带域名锁定）| Configure MCP server (recommended: with domain lock):

在项目根目录创建或编辑 opencode.json：

Create or edit opencode.json in the project root:

{
  "mcpServers": {
    "wdns": {
      "command": "./dist/wdns",
      "args": ["-k", "your-key", "mcp", "-d", "example.com"]
    }
  }
}

使用环境变量 | Using environment variables:

{
  "mcpServers": {
    "wdns": {
      "command": "./dist/wdns",
      "args": ["mcp"],
      "env": {
        "WEST_API_DOMAIN_KEY": "your-key",
        "WEST_DOMAIN": "example.com"
      }
    }
  }
}

不锁定域名（多域名）| Without domain lock (multi-domain):

{
  "mcpServers": {
    "wdns": {
      "command": "./dist/wdns",
      "args": ["mcp"],
      "env": {
        "WEST_USERNAME": "your-username",
        "WEST_API_PASSWORD": "your-password"
      }
    }
  }
}

使用 bun 运行 | Run with bun:

{
  "mcpServers": {
    "wdns": {
      "command": "bun",
      "args": ["run", "src/index.ts", "-k", "your-key", "mcp", "-d", "example.com"]
    }
  }
}

使用 JS 单文件 | Use the JS bundle:

{
  "mcpServers": {
    "wdns": {
      "command": "node",
      "args": ["./dist/wdns.mjs", "-k", "your-key", "mcp", "-d", "example.com"]
    }
  }
}

配置完成后启动 OpenCode，即可通过自然语言管理 DNS 记录。

After configuration, start OpenCode and manage DNS records via natural language.

AI Agent 技能文档 | AI Agent skill documentation

docs/SKILL.md 提供了面向 AI Agent 的完整 CLI 使用文档，包含所有命令的详细参数、示例和最佳实践。可作为 system prompt 或知识库注入给任意 Agent 使用。

docs/SKILL.md provides complete CLI usage documentation for AI agents, including all command parameters, examples, and best practices. It can be injected as system prompt or knowledge base for any agent.

记录类型 | Record types

线路路由 | Route lines

线路路由实现智能 DNS —— 不同运营商/地区返回不同解析结果：

Route lines enable GeoDNS — different responses for different ISPs/regions:

智能 DNS 示例 | GeoDNS example

# 电信用户解析到 1.1.1.1 | Telecom users resolve to 1.1.1.1
wdns modify example.com -t A -H www -v 1.1.1.1 -l telecom

# 联通用户解析到 2.2.2.2 | Unicom users resolve to 2.2.2.2
wdns modify example.com -t A -H www -v 2.2.2.2 -l unicom

# 移动用户解析到 3.3.3.3 | Mobile users resolve to 3.3.3.3
wdns modify example.com -t A -H www -v 3.3.3.3 -l mobile

# 海外用户解析到 4.4.4.4 | Overseas users resolve to 4.4.4.4
wdns modify example.com -t A -H www -v 4.4.4.4 -l overseas

License

Private