mcp-pihole
MCP server for Pi-hole v6. Manage blocklists, DNS blocking, domain allow/deny lists, and query diagnostics through the Model Context Protocol.
Prerequisites
- Python 3.14+
- uv
- Pi-hole v6+ with the REST API enabled
Setup
uv sync
Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
PIHOLE_URL |
Yes | Base URL of your Pi-hole instance (e.g., http://192.168.0.160:8080) |
PIHOLE_PASSWORD |
No | Web interface password. Omit or leave empty for passwordless instances. |
Claude Code
claude mcp add pihole \
-e PIHOLE_URL=http://192.168.0.160:8080 \
-e PIHOLE_PASSWORD=yourpassword \
-- uvx mcp-pihole
Or add to .claude/settings.json:
{
"mcpServers": {
"pihole": {
"command": "uvx",
"args": ["mcp-pihole"],
"env": {
"PIHOLE_URL": "http://192.168.0.160:8080",
"PIHOLE_PASSWORD": "yourpassword"
}
}
}
}
Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"pihole": {
"command": "uvx",
"args": ["mcp-pihole"],
"env": {
"PIHOLE_URL": "http://192.168.0.160:8080",
"PIHOLE_PASSWORD": "yourpassword"
}
}
}
}
Tools
Diagnostics
| Tool | Description |
|---|---|
get_status |
Pi-hole status summary (queries, blocked count, blocking state) |
get_top_domains |
Top queried or blocked domains |
get_top_clients |
Top DNS clients by query count |
get_queries |
Recent DNS query log with cursor-based pagination |
get_version |
Pi-hole FTL version information |
Blocklist Management
| Tool | Description |
|---|---|
get_lists |
List all configured blocklists |
add_list |
Add a blocklist URL |
remove_list |
Remove a blocklist by URL |
update_list |
Enable/disable a blocklist or update its comment |
update_gravity |
Rebuild gravity database (required after blocklist changes) |
Domain Management
| Tool | Description |
|---|---|
get_domains |
List allow/deny domains (exact or regex) |
add_domain |
Add a domain to allow or deny list |
remove_domain |
Remove a domain from allow or deny list |
search_domains |
Check if a domain is blocked and by which list |
DNS Control and DHCP
| Tool | Description |
|---|---|
get_blocking_status |
Current DNS blocking status and timer |
set_blocking |
Enable/disable blocking, optionally with a timer |
get_dhcp_leases |
Current DHCP leases |
restart_dns |
Restart the DNS resolver |
Development
uv sync
uv run pytest tests/ -x -q
uv run ruff check src/ tests/
uv run pyright src/
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
mcp_pihole-0.2.0.tar.gz
(7.8 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mcp_pihole-0.2.0.tar.gz.
File metadata
- Download URL: mcp_pihole-0.2.0.tar.gz
- Upload date:
- Size: 7.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
87d75cd3faf01ca875e67f0c910ac9f59283aeef1a360a39162ad0ff20a66f07
|
|
| MD5 |
67a9768cf6318d24c277dc9c837bb631
|
|
| BLAKE2b-256 |
16e4dcf4998e71b0e01ac6087d04bd78f8f07776fbc97fc59c3595a70a2979db
|
Provenance
The following attestation bundles were made for mcp_pihole-0.2.0.tar.gz:
Publisher:
release.yml on obrien-matthew/mcp-pihole
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
mcp_pihole-0.2.0.tar.gz -
Subject digest:
87d75cd3faf01ca875e67f0c910ac9f59283aeef1a360a39162ad0ff20a66f07 - Sigstore transparency entry: 1456783026
- Sigstore integration time:
-
Permalink:
obrien-matthew/mcp-pihole@0c6ca23659d05108e07708a2fefa224e801b6df2 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/obrien-matthew
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@0c6ca23659d05108e07708a2fefa224e801b6df2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file mcp_pihole-0.2.0-py3-none-any.whl.
File metadata
- Download URL: mcp_pihole-0.2.0-py3-none-any.whl
- Upload date:
- Size: 10.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
964f0ad794c36b60898d6202f91c2db8e1f93cd8f0dadccdc520a313b645e982
|
|
| MD5 |
7e6612cc99169e4213b99c85b8d9fe38
|
|
| BLAKE2b-256 |
2d07d01004887cf5e990914565067100afb76e09948c0ca5e375f229ee92979f
|
Provenance
The following attestation bundles were made for mcp_pihole-0.2.0-py3-none-any.whl:
Publisher:
release.yml on obrien-matthew/mcp-pihole
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
mcp_pihole-0.2.0-py3-none-any.whl -
Subject digest:
964f0ad794c36b60898d6202f91c2db8e1f93cd8f0dadccdc520a313b645e982 - Sigstore transparency entry: 1456783255
- Sigstore integration time:
-
Permalink:
obrien-matthew/mcp-pihole@0c6ca23659d05108e07708a2fefa224e801b6df2 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/obrien-matthew
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@0c6ca23659d05108e07708a2fefa224e801b6df2 -
Trigger Event:
push
-
Statement type:
