Skip to main content
Glama
Koru Shield MCP Server

Koru Shield MCP Server

Official

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_profiles / get_profile

List and inspect DNS protection profiles

create_rule / list_rules / delete_rule

Block or allow domains per profile

list_filter_categories / set_filter_category

Toggle categories (adult, gambling, social media...)

simulate_policy

Check if a domain would be blocked right now

get_logs

Recent DNS queries: allowed, blocked, when

analytics_summary

Totals, blocked percentage, encrypted queries

list_schedules / create_schedule / delete_schedule

Time windows (bedtime, homework hours)

list_devices

Devices enrolled per profile

get_entitlements

Plan, limits, current usage

get_referral_code

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-server

Set 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-server

Or 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 start

Test with the MCP Inspector:

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

License

MIT

Available Tools

16 tools
analytics_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

    B3.4/5.0

    Scored across 16 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Connects 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.
      16
      81 npm
      8
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI assistants to manage NextDNS profiles, settings, logs, analytics, and security configurations through 70+ operations via the Model Context Protocol.
      8
      15
      MIT