koru-shield

Koru Shield MCP 服务

通过 AI 助手管理您的 Koru Shield DNS 保护。屏蔽域名、检查策略、查看被屏蔽的查询、管理计划等，全部通过自然语言完成。

功能

将您的 Koru Shield 账户作为 Model Context Protocol 工具提供：

工具	功能
list_profiles / get_profile	列出并查看 DNS 保护配置文件
create_rule / list_rules / delete_rule	按配置文件屏蔽或允许域名
list_filter_categories / set_filter_category	切换类别（成人内容、赌博、社交媒体等）
simulate_policy	检查某个域名现在是否会被屏蔽
get_logs	最近的 DNS 查询：允许或屏蔽，以及时间
analytics_summary	总数、屏蔽比例、加密查询
list_schedules / create_schedule / delete_schedule	时间段（就寝时间、作业时间）
list_devices	各配置文件中注册的设备
get_entitlements	套餐、限制、当前用量
get_referral_code	您的推荐链接

连接后可用的提示词示例：

• “在 Kids 配置文件中屏蔽 tiktok.com”
• “youtube.com 现在会在 Kids 中被屏蔽吗？”
• “显示今天被屏蔽的内容”
• “为整个家庭开启成人内容过滤”
• “为 Kids 配置文件添加一个工作日晚上 9 点到早上 7 点的就寝计划”

设置

1. 获取 Koru Shield API 密钥

登录 https://my.korushield.com，前往 API keys，然后创建一个密钥。复制该密钥。

2. 安装

无需安装。直接使用 npx 运行：

npx -y korushield-mcp-server

将密钥设置为环境变量：

export KORU_SHIELD_API_KEY="your-key-here"

可选：KORU_SHIELD_API_URL 可覆盖 API 基础 URL（默认值为 https://my.korushield.com/api）。

3. 连接 AI 客户端

Claude Code

claude mcp add koru-shield -- npx -y korushield-mcp-server

（Claude Code 会传递环境变量，因此请先导出 KORU_SHIELD_API_KEY。或者使用下方的 HTTP 传输并添加标头。）

Cursor / VS Code

将以下内容添加到 MCP 配置中（~/.cursor/mcp.json 或 VS Code mcp.json）：

{
  "mcpServers": {
    "koru-shield": {
      "command": "npx",
      "args": ["-y", "korushield-mcp-server"],
      "env": {
        "KORU_SHIELD_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "koru-shield": {
      "command": "npx",
      "args": ["-y", "korushield-mcp-server"],
      "env": {
        "KORU_SHIELD_API_KEY": "your-key-here"
      }
    }
  }
}

HTTP 传输（远程）

适用于通过 HTTP 连接的客户端（Agent、托管环境）：

MCP_TRANSPORT=http PORT=3000 KORU_SHIELD_API_KEY="your-key-here" npx -y korushield-mcp-server

也可以在每个请求中传递密钥，而不是使用环境变量：

POST https://your-host/mcp
Authorization: Bearer <koru-shield-api-key>

健康检查：GET /healthz。

安全说明

• 您的 API 密钥可以完全控制 Koru Shield 账户，包括删除规则和计划。请像对待密码一样保护它。
• 建议为 AI 助手使用专用 API 密钥，以便单独撤销。
• 除 Koru Shield API 外，服务不会在任何地方记录或传输您的密钥。

开发

npm install
npm run build
npm start

使用 MCP Inspector 进行测试：

KORU_SHIELD_API_KEY="your-key-here" npm run inspector

许可证

MIT