# AdGuard Home MCP MCP

> AdGuard Home MCP lets your AI agent manage all network filtering, DNS settings, and security policies for your ad blocker instance. Use natural conversation to check server health, add specific client IPs, update filter lists, or toggle global protection—all without touching a web dashboard or command line.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** dns-filtering, ad-blocking, network-security, privacy, parental-controls, server-monitoring

## Description

Managing network privacy usually means wading through complex GUIs or wrestling with APIs. This MCP changes that. You simply tell your agent what you need done for your AdGuard Home setup, and it executes the commands. Need to know if a specific website is getting blocked? Just ask. Want to change the upstream DNS servers because your current ones are slow? Tell the agent. Even configuring security settings for individual devices or adding permanent client IPs becomes a simple conversation. This integration makes deep network control available through natural language, positioning it as a core utility in the Vinkius catalog for any advanced AI workflow.

## Tools

### add_client
Adds a new device or IP address to the list of managed clients on your network.

### add_filter_url
Applies an additional blocklist URL filter to improve filtering capability.

### add_rewrite
Creates a specific DNS rewrite rule, forcing traffic for certain domains to a different location.

### add_static_lease
Assigns and reserves a permanent IP address for a client device using DHCP settings.

### check_host
Validates whether a specific domain name is currently being filtered or blocked by the system.

### configure_tls
Sets up and verifies secure transport layer settings for the AdGuard Home instance.

### get_dhcp_status
Retrieves current information about the DHCP server status, including lease details.

### get_dns_info
Shows the active DNS configuration details, including resolvers and cache parameters.

### get_filtering_status
Retrieves a report on current filtering rules and available blocklist/allowlist settings.

### get_query_log_config
Checks and updates the retention policy and logging levels for the query log.

### get_query_log
Fetches a list of historical DNS query entries, showing what was looked up over time.

### get_stats
Generates real-time usage statistics, such as the number of DNS queries processed in a given time frame.

### get_status
Provides a quick check on the overall operational status and health of the AdGuard Home server.

### get_tls_status
Reports the current state, expiration date, and cipher support for TLS settings.

### list_blocked_services
Lists all predefined services or domains that are currently configured to be blocked system-wide.

### list_clients
Retrieves a comprehensive list of every device (client) connected to the network and monitored by AdGuard Home.

### list_rewrites
Displays all active DNS rewrite rules that redirect domain traffic.

### search_clients
Filters the list of clients to find a specific device using its name or IP address.

### set_dns_config
Updates the primary DNS resolver settings for the entire network.

### set_protection
Toggles the overall protection status of the ad blocker, either enabling or disabling it globally.

### set_user_rules
Applies specific filtering rules that only affect certain named users or client groups.

### update_blocked_services
Modifies the schedule or list of services that are blocked at a system level.

### update_query_log_config
Changes how often and how long query logs are kept, controlling data retention.

## Prompt Examples

**Prompt:** 
```
What is the current status of my AdGuard Home server?
```

**Response:** 
```
I've checked your server. AdGuard Home v0.107.43 is currently running. Protection is ENABLED, and the DNS server is listening on port 53.
```

**Prompt:** 
```
Disable protection for the next 10 minutes.
```

**Response:** 
```
Global protection has been disabled. I've set a duration of 600,000ms, so it will automatically re-enable in 10 minutes.
```

**Prompt:** 
```
Check if 'doubleclick.net' is currently being filtered for client 192.168.1.50.
```

**Response:** 
```
Yes, 'doubleclick.net' is being filtered for that client. It is currently blocked by the 'AdGuard DNS filter' list.
```

## Capabilities

### Check server health and status
Get real-time reports on the AdGuard Home instance's operational state, including version number and active ports.

### Control network protection rules
Globally enable or disable filtering, safe browsing modes, or parental controls, even setting a specific time limit for the change.

### Update DNS and filter settings
Modify upstream DNS servers, add new blocklist URLs, or set up custom rewriting rules for domains.

### Manage client devices
List all connected clients, search for specific IPs, add new client records, and even assign permanent IP addresses (static leases).

### Audit network traffic
Check if a specific domain is being filtered or blocked for any given client, and review historical query logs.

## Use Cases

### Troubleshooting a blocked website for one user
A client reports that site X won't load. Instead of checking the web UI, you ask your agent to run `check_host` on 'sitex.com'. The agent replies instantly if it's filtered or not, letting you know whether to fix a filter rule or tell the user the block is intentional.

### Onboarding a new permanent device
A smart TV needs a reliable IP address. You run `add_static_lease` via your agent, assigning it an IP and making sure its records are permanent. Then you use `list_clients` to confirm the entry shows up correctly.

### Auditing filter changes for compliance
The boss asks why specific domains were blocked last week. You ask your agent to pull the `get_query_log`, filtering by date range, and then use `list_rewrites` to show what rules were in place at that time.

### Making a quick system-wide change
The primary DNS resolver fails. Instead of logging into the GUI, you tell your agent to run `set_dns_config` immediately using the backup IPs and confirm the update with `get_dhcp_status`.

## Benefits

- Instead of navigating complex web dashboards to check if a host is blocked, you just ask the agent. The `check_host` tool tells you immediately if that domain is filtered or not.
- Need to temporarily disable filtering for maintenance? You can't mess with global settings and forget to turn it back on. Use the `set_protection` tool to toggle status globally and even set an automatic time limit.
- Managing IP assignments used to mean manually opening the client list and adding entries. Now, you use `add_client` or `add_static_lease` via simple conversation to lock down device IPs instantly.
- The agent makes it easy to manage DNS configuration. You can run `get_dns_info` to validate current resolvers, then use `set_dns_config` if they're wrong—all without touching a settings page.
- Debugging network issues? Don't just guess. Use the agent to retrieve historical data with `get_query_log`, seeing exactly what queries were made and when.

## How It Works

The bottom line is that your AI client translates complex network commands into simple chat interactions.

1. Subscribe to this MCP and provide your AdGuard Home Base URL along with the necessary credentials.
2. Connect your preferred AI agent (like Claude or Cursor) to the Vinkius catalog and select this integration.
3. Use natural language prompts. Instead of navigating menus, you simply ask the agent to perform an action—'Block ads for site X now,' or 'Show me all active clients.'

## Frequently Asked Questions

**How do I check if an IP is already assigned when using add_static_lease?**
The agent will confirm the current status of that address. You can first run `get_dhcp_status` to see all existing leases, and then use the agent to add a static lease if the IP is free.

**Can I view historical queries using get_query_log?**
Yes. You can ask your agent to pull the query log for a specific date range or client, letting you see exactly what was looked up at that time.

**What if I need to change the primary DNS resolver? Do I use set_dns_config?**
Yes. You tell your agent to run `set_dns_config` and provide the new IP addresses. The agent handles applying those changes across the entire network.

**How do I see if a specific domain is blocked for me? Use check_host.**
Just ask your agent to run `check_host` on the domain name you care about. It will tell you immediately whether it's filtered by an active rule or not.

**Is there a tool to update my filter lists? Should I use add_filter_url?**
Yes, `add_filter_url` lets you append new blocklist URLs. You just give the agent the list and tell it where to apply them.

**I need to see performance metrics like total queries or blocked counts. What tool should I use? Use get_stats.**
The `get_stats` tool provides a detailed summary of your network traffic and query volume. You'll get hard numbers on everything, including the count of successful DNS lookups and how many requests were filtered out.

**I want to force a specific website name to always point to another IP address. Is `add_rewrite` for that? Use add_rewrite.**
Yes, `add_rewrite` lets you create a DNS rewrite rule. This means you're manually telling the network to treat one domain as if it were another, overriding standard resolution.

**How do I onboard a brand new device onto the network? Should I use add_client?**
`add_client` lets your agent register a new client's unique identifiers. This ensures that device gets proper tracking and allows you to apply specific security settings just for it.

**Can I check if a specific website is being blocked for a specific client?**
Yes, use the `check_host` tool. Provide the domain name and optionally the client IP to see if it's filtered and which rule is responsible.

**Is it possible to pause the ad-blocking globally for a short period?**
Yes. The `set_protection` tool allows you to disable filtering globally. You can also specify a duration in milliseconds if you want it to re-enable automatically.

**How do I add a new blocklist URL using the AI?**
Simply use the `add_filter_url` action. You'll need to provide a name for the filter, the URL of the list, and specify if it's a whitelist or blocklist.