# koru-shield

Manage Koru Shield DNS protection from an AI assistant: edit domain rules, inspect queries, and check whether a domain would be blocked.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1
- Author: KoruShield
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/KoruShield/koru-shield-mcp
- Updated: 2026-10-06
- HTML: https://affpapa.org/en/nevibecode/mcp/koru-shield

## What it does

The MCP server connects an assistant to a Koru Shield account. It can inspect profiles and enrolled devices, add or remove domain rules, change filtering categories, and test a domain against the current policy. It also provides DNS query logs, analytics summaries, schedules, plan details, and a referral code.

You need a Koru Shield API key. It grants account control, including the ability to delete rules and schedules, so treat it like a password. The server runs with `npx -y korushield-mcp-server`; Claude Code can connect over HTTP or stdio. For a stdio setup, pass the key through `KORU_SHIELD_API_KEY`.

The server sends the key only to the Koru Shield API and does not write it to logs. Because the key allows changes to account settings, consider its access before connecting an assistant.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://mcp.korushield.com/mcp`
- Environment variables: `KORU_SHIELD_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http koru-shield https://mcp.korushield.com/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env KORU_SHIELD_API_KEY=<KORU_SHIELD_API_KEY> --transport stdio koru-shield -- npx -y korushield-mcp-server
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add koru-shield --url https://mcp.korushield.com/mcp
```

2. **Platform CLI**
```bash
codex mcp add koru-shield --env KORU_SHIELD_API_KEY=<KORU_SHIELD_API_KEY> -- npx -y korushield-mcp-server
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "koru-shield": {
            "url": "https://mcp.korushield.com/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "koru-shield": {
            "command": "npx",
            "args": [
                "-y",
                "korushield-mcp-server"
            ],
            "env": {
                "KORU_SHIELD_API_KEY": "<KORU_SHIELD_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "koru-shield": {
            "type": "http",
            "url": "https://mcp.korushield.com/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "koru-shield": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "korushield-mcp-server"
            ],
            "env": {
                "KORU_SHIELD_API_KEY": "<KORU_SHIELD_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http koru-shield https://mcp.korushield.com/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e KORU_SHIELD_API_KEY=<KORU_SHIELD_API_KEY> koru-shield npx -y korushield-mcp-server
```
Replace <…> with your own values

## When to use it
- block a domain for a chosen profile
- check whether a site would be filtered now
- inspect blocked DNS queries
- set a schedule for a profile
- change DNS filtering categories

## Example prompts
- Block `tiktok.com` on the Kids profile.
- Check whether `youtube.com` would be blocked on Kids right now.
- Show the DNS queries blocked today.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74569
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89899

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md