Headless Domains MCP 服务器

Headless Domains 的官方模型上下文协议 (MCP) 服务器。该服务器向 Claude Desktop、Cursor 和 Windsurf 等兼容 MCP 的客户端公开 Headless Domains API 操作。

功能

search_domain：检查域名是否可用
lookup_whois：查看已注册身份信息
register_domain：使用 API 密钥注册域名
sync_bio：使用 API 密钥同步代理/个人资料简介内容
自动传输选择：
- 本地 MCP 客户端使用 stdio
- 托管部署时，若存在 PORT 则使用 sse

要求

Python 3.10+
可选：用于认证工具的 Headless Domains API 密钥

本地设置

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

环境变量

变量	必需	默认值	用途
`HEADLESSDOMAINS_API_KEY`	否	未设置	为认证端点发送 `X-API-Key`
`HEADLESSDOMAINS_API_BASE_URL`	否	`https://headlessdomains.com/api/v1`	覆盖 API 基础 URL
`HEADLESSDOMAINS_TIMEOUT`	否	`20`	HTTP 超时时间（秒）
`HEADLESSDOMAINS_REGISTER_PATH`	否	`/domains/register`	若 API 变更，覆盖注册端点路径
`HEADLESSDOMAINS_SYNC_BIO_PATH`	否	`/domains/{domain}/bio`	若 API 变更，覆盖同步简介端点路径
`MCP_TRANSPORT`	否	auto	强制使用 `stdio` 或 `sse` 等传输方式
`HOST`	否	`0.0.0.0`	SSE 模式的绑定主机
`PORT`	否	未设置	若存在，则以 `sse` 模式启动服务器

本地运行

对于本地 MCP 客户端，服务器默认使用 stdio：

python server.py

你也可以通过 MCP CLI 运行它：

mcp run server.py

Claude Desktop 配置

在 claude_desktop_config.json 中添加服务器条目：

{
  "mcpServers": {
    "headlessdomains": {
      "command": "mcp",
      "args": [
        "run",
        "/absolute/path/to/headlessdomains-mcp/server.py"
      ],
      "env": {
        "HEADLESSDOMAINS_API_KEY": "your-api-key-here"
      }
    }
  }
}

如果你暂时不需要认证工具，可以省略 HEADLESSDOMAINS_API_KEY。

托管 SSE 模式

当存在 PORT 时，server.py 会自动启动 SSE 传输：

PORT=8080 python server.py

典型的 Railway 风格启动方式：

HOST=0.0.0.0 PORT=8080 python server.py

工具说明

`register_domain`

需要 HEADLESSDOMAINS_API_KEY
发送包含 domain、namespace、years、agreed_to_terms (true) 和 payment_method ("gems") 的基础负载
接受 extra_payload_json 以处理工具中未硬编码的 API 字段

示例：

{
  "domain": "myagent.agent",
  "years": 1,
  "extra_payload_json": "{\"owner_email\":\"me@example.com\"}"
}

`sync_bio`

需要 HEADLESSDOMAINS_API_KEY
同步至 /domains/<domain>/bio 端点
发送 domain、bio 和 bio_markdown
接受 extra_payload_json 以处理任何额外的 API 字段（如 name、x、github 等）

示例：

{
  "domain": "myagent.agent",
  "bio_markdown": "# About Me",
  "extra_payload_json": "{\"name\":\"My Agent Name\", \"x\":\"twitter_handle\"}"
}

Docker

构建：

docker build -t headlessdomains-mcp .

运行：

docker run --rm -p 8080:8080 \
  -e PORT=8080 \
  -e HEADLESSDOMAINS_API_KEY=your-api-key-here \
  headlessdomains-mcp

冒烟测试

安装依赖后：

python -m py_compile server.py
python - <<'PY'
import server
print(server.search_domain("example.agent"))
print(server.lookup_whois("test.agent"))
PY

注意事项

/temp-specs 在 .gitignore 中被忽略，以确保本地规划文档不会进入版本控制。

This server cannot be installed

F

license - not found

-

quality - not tested

C

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Headless Domains MCP Server