Koru Shield MCP Server
OfficialManage a Koru Shield DNS filtering account through MCP tools — inspect profiles, block/allow domains and categories, run schedules, and review DNS activity.
List and inspect DNS protection profiles (
list_profiles,get_profile)Create, list, and delete custom allow/deny domain rules per profile (
create_rule,list_rules,delete_rule)List and toggle filter categories like adult content, gambling, social media (
list_filter_categories,set_filter_category)Simulate whether a domain would be blocked right now, and why (
simulate_policy)Review recent DNS query logs with action and profile filters (
get_logs)Get activity analytics: totals, blocked %, IPv4/IPv6, encrypted queries (
analytics_summary)Create, list, and delete time-based schedules such as bedtime or homework hours (
list_schedules,create_schedule,delete_schedule)List enrolled devices and their protection status per profile (
list_devices)Check plan, limits, and current usage (
get_entitlements)Get the account referral code and link (
get_referral_code)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Koru Shield MCP Server Block tiktok.com on the Kids profile"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Koru Shield MCP Server
Manage your Koru Shield DNS protection through AI assistants. Block domains, check policies, review blocked queries, manage schedules, and more, all through natural language.
What it does
Exposes your Koru Shield account as Model Context Protocol tools:
Tool | What it does |
| List and inspect DNS protection profiles |
| Block or allow domains per profile |
| Toggle categories (adult, gambling, social media...) |
| Check if a domain would be blocked right now |
| Recent DNS queries: allowed, blocked, when |
| Totals, blocked percentage, encrypted queries |
| Time windows (bedtime, homework hours) |
| Devices enrolled per profile |
| Plan, limits, current usage |
| Your referral link |
Example prompts once connected:
"Block tiktok.com on the Kids profile"
"Would youtube.com be blocked on Kids right now?"
"Show me what got blocked today"
"Turn on adult content filtering for the whole house"
"Add a bedtime schedule 9pm to 7am on weekdays for the Kids profile"
Related MCP server: Cloudflare Control
Setup
1. Get a Koru Shield API key
Sign in at https://my.korushield.com, go to API keys, and create one. Copy the key.
2. Install
No install needed. Run directly with npx:
npx -y korushield-mcp-serverSet your key as an environment variable:
export KORU_SHIELD_API_KEY="your-key-here"Optional: KORU_SHIELD_API_URL overrides the API base URL (default https://my.korushield.com/api).
3. Connect your AI client
Claude Code
claude mcp add koru-shield -- npx -y korushield-mcp-server(Claude Code passes environment through, so export KORU_SHIELD_API_KEY first. Or use the HTTP transport below with a header.)
Cursor / VS Code
Add to your MCP config (~/.cursor/mcp.json or VS Code mcp.json):
{
"mcpServers": {
"koru-shield": {
"command": "npx",
"args": ["-y", "korushield-mcp-server"],
"env": {
"KORU_SHIELD_API_KEY": "your-key-here"
}
}
}
}Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"koru-shield": {
"command": "npx",
"args": ["-y", "korushield-mcp-server"],
"env": {
"KORU_SHIELD_API_KEY": "your-key-here"
}
}
}
}HTTP transport (remote)
For clients that connect over HTTP (agents, hosted setups):
MCP_TRANSPORT=http PORT=3000 KORU_SHIELD_API_KEY="your-key-here" npx -y korushield-mcp-serverOr pass the key per-request instead of the env var:
POST https://your-host/mcp
Authorization: Bearer <koru-shield-api-key>Health check: GET /healthz.
Security notes
Your API key grants full control of your Koru Shield account, including deleting rules and schedules. Treat it like a password.
Prefer a dedicated API key for AI assistants so you can revoke it independently.
The server never logs or transmits your key anywhere except to the Koru Shield API.
Development
npm install
npm run build
npm startTest with the MCP Inspector:
KORU_SHIELD_API_KEY="your-key-here" npm run inspectorLicense
MIT
Available Tools
16 toolsanalytics_summaryBInspect
Summary of DNS activity: total queries, blocked vs allowed counts, blocked percentage, IPv4/IPv6, encrypted queries.
Inputs: to, from, profile_id.
create_ruleBInspect
Create a custom allow or deny rule for a domain on a profile. Use kind=deny to block a domain, kind=allow to explicitly permit it.
Inputs: kind (required), domain (required), profile_id (required), note.
create_scheduleCInspect
Create a time-based schedule on a profile. Rules and filter categories can reference schedules to apply only during the window.
Inputs: end (required), days (required), name (required), start (required), +2 more.
delete_ruleAInspect
Delete a custom rule from a profile. Destructive: the rule stops applying immediately.
Inputs: rule_id (required), profile_id (required).
delete_scheduleAInspect
Delete a schedule from a profile. Destructive: rules referencing it lose their time window.
Inputs: profile_id (required), schedule_id (required).
get_entitlementsAInspect
Get the account plan, limits (max rules, profiles, devices), and current usage.
Inputs: no named parameters.
get_logsAInspect
Get recent DNS query logs: what was queried, allowed or blocked, and when. Useful for reviewing activity or investigating a block.
Inputs: limit, action, profile_id.
get_profileCInspect
Get details of a single profile.
Inputs: profile_id (required).
get_referral_codeAInspect
Get the account referral code and link for the give-a-month-get-a-month program.
Inputs: no named parameters.
list_devicesBInspect
List devices enrolled on a profile and their protection status.
Inputs: profile_id (required).
list_filter_categoriesAInspect
List filter categories (adult content, gambling, social media, etc.) and whether each is enabled on a profile.
Inputs: profile_id (required).
list_profilesAInspect
List all DNS protection profiles on the account (e.g. Kids, Work, IoT).
Inputs: no named parameters.
list_rulesBInspect
List custom allow/deny rules for a profile.
Inputs: profile_id (required).
list_schedulesBInspect
List time-based schedules on a profile (e.g. bedtime 21:00-07:00 on weekdays).
Inputs: profile_id (required).
set_filter_categoryCInspect
Enable or disable a filter category on a profile.
Inputs: slug (required), enabled (required), profile_id (required).
simulate_policyAInspect
Check what the profile policy would do for a domain right now: allowed, blocked, and why. Does not change anything.
Inputs: domain (required), profile_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource or action: profiles, rules, filter categories, schedules, logs, analytics, devices, and account info. Overlap is minimal; simulate_policy, get_logs, and analytics_summary serve different query intents. No two tools appear to do the same thing.
Nearly all tools follow a consistent verb_noun snake_case pattern (list_profiles, create_rule, set_filter_category). The only deviation is analytics_summary, which is a noun phrase rather than verb_noun. Still highly readable and predictable.
16 tools is slightly above the ideal 3–15 range but reasonable given the multiple sub-resources (profiles, rules, categories, schedules, devices, analytics, account). Each tool maps to a clear operation, with no obvious redundancy.
The surface lacks profile lifecycle operations (create/update/delete profile), rule and schedule updates, and device enrollment/removal. Only list operations exist for devices and entitlements. These gaps will force agents to work around missing CRUD for core resources.
Maintenance
Related MCP Connectors
Register, transfer and manage domain names and DNS from your AI agent.
Connect custom domains via AI agents: DNS pre-flight checks, hand-off connect sessions and checks.
Manage hosts, redirects, SSL, and traffic analytics from Claude and other AI assistants.
Buy & manage domains from any AI chat: availability, register, DNS, email forwarding, AI bot stats.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects AI assistants to Pi-hole network-wide ad blocker, enabling monitoring of DNS traffic statistics, controlling blocking settings, managing whitelist/blacklist domains, viewing query logs, and performing maintenance tasks through natural language.1681 npm8MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Cloudflare infrastructure including DNS records, cache purging, SSL settings, Workers, and analytics through the Cloudflare API. Eliminates dashboard context-switching by allowing natural language control of domain management and infrastructure operations.-
- AlicenseCqualityBmaintenanceEnables AI assistants to manage NextDNS profiles, settings, logs, analytics, and security configurations through 70+ operations via the Model Context Protocol.815MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Cloudflare DNS zones and records, including listing, creating, updating, and deleting DNS records through natural language.6MIT