Provides tools to manage a Pi-hole DNS server, including enabling/disabling DNS blocking, retrieving statistics and status, querying top blocked domains, and testing connectivity.
Click on "Install 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., "@Pi-hole MCP Server Show me the top 10 blocked domains"
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.
A Model Context Protocol (MCP) server for interacting with Pi-hole DNS servers from AI assistants like Cursor. This allows you to manage your Pi-hole directly through natural language commands in your IDE.
Universal Compatibility: Works with both legacy and modern Pi-hole installations, automatically detecting the API version and using the appropriate authentication method.
š Secure Credential Management: Encrypted storage of Pi-hole credentials using system keyring
šÆ Easy Setup: Simple CLI-based configuration and authentication
š Rich MCP Integration: Full support for Pi-hole operations through the MCP protocol
š Comprehensive Statistics: Access to detailed Pi-hole analytics and metrics
š ļø Robust CLI: Complete command-line interface for Pi-hole management
š Security First: Secure API key handling and SSL verification
š Universal Compatibility: Supports both legacy and modern Pi-hole API versions
š¤ Automatic Detection: Automatically detects and adapts to your Pi-hole's API version
Related MCP server: Pi-hole MCP Server
Python 3.10 or higher
Access to a Pi-hole instance with either:
Legacy Pi-hole: API key (found in Admin ā Settings ā API/Web interface ā Show API token)
Modern Pi-hole: Web interface password (your admin login password)
uv (recommended) or pip
# Install globally to ~/.local/
pip install --user pihole-mcp-server
# Or using uv
uv tool install pihole-mcp-server# Clone the repository
git clone https://github.com/brettbergin/pihole-mcp-server.git
cd pihole-mcp-server
# Install with uv (recommended)
uv sync
uv pip install -e .
# Or with pip
pip install -e .First, you need to authenticate with your Pi-hole instance:
pihole-mcp-cli loginThe tool will automatically detect your Pi-hole's API version and prompt for appropriate credentials. If you don't provide specific authentication options, it will guide you through an interactive setup process.
For Legacy Pi-hole:
Pi-hole hostname or IP: Your Pi-hole server address
Port: Usually 80 (HTTP) or 443 (HTTPS)
API key: Found in Pi-hole Admin ā Settings ā API/Web interface ā Show API token
HTTPS: Whether to use secure connection
SSL verification: Whether to verify SSL certificates
For Modern Pi-hole:
Pi-hole hostname or IP: Your Pi-hole server address
Port: Usually 8080 (HTTP) or 8443 (HTTPS)
Web password: Your Pi-hole admin interface password
HTTPS: Whether to use secure connection
SSL verification: Whether to verify SSL certificates
If you prefer to specify the authentication method manually:
# For legacy Pi-hole with API key
pihole-mcp-cli login --host 192.168.1.100 --api-key YOUR_API_KEY
# For modern Pi-hole with web password
pihole-mcp-cli login --host 192.168.1.100 --port 8080 --web-password YOUR_PASSWORD
# Read credentials from stdin (useful for automation)
echo "YOUR_API_KEY" | pihole-mcp-cli login --host 192.168.1.100 --api-key -
echo "YOUR_PASSWORD" | pihole-mcp-cli login --host 192.168.1.100 --port 8080 --web-password -pihole-mcp-cli testAdd the following to your Cursor MCP configuration:
{
"mcpServers": {
"pihole": {
"command": "pihole-mcp-server",
"args": []
}
}
}Once configured, you can use natural language commands in Cursor:
"Disable Pi-hole for 30 minutes"
"Show me Pi-hole statistics"
"Enable Pi-hole blocking"
"What are the top blocked domains?"
Command | Description |
| Configure and store Pi-hole credentials |
| Show Pi-hole status and statistics |
| Enable Pi-hole DNS blocking |
| Disable Pi-hole DNS blocking |
| Test connection and authentication |
| Show configuration information |
| Remove stored credentials |
Option | Description | Example |
| Pi-hole hostname or IP |
|
| Pi-hole port number |
|
| API key for legacy Pi-hole |
|
| Web password for modern Pi-hole |
|
| Use HTTPS connection |
|
| Disable SSL verification |
|
| Request timeout in seconds |
|
# Configure Pi-hole connection (interactive mode - auto-detects API version)
pihole-mcp-cli login --host 192.168.1.100
# Configure legacy Pi-hole with API key
pihole-mcp-cli login --host 192.168.1.100 --api-key YOUR_API_KEY --use-https
# Configure modern Pi-hole with web password
pihole-mcp-cli login --host 192.168.1.100 --port 8080 --web-password YOUR_PASSWORD
# Check current status
pihole-mcp-cli status
# Disable Pi-hole for 1 hour
pihole-mcp-cli disable --minutes 60
# Disable Pi-hole for 30 seconds
pihole-mcp-cli disable --seconds 30
# Enable Pi-hole
pihole-mcp-cli enable
# Show detailed help for a command
pihole-mcp-cli disable --helpThe MCP server provides the following tools for AI assistants:
pihole_status - Get current Pi-hole status and basic statistics
pihole_enable - Enable Pi-hole DNS blocking
pihole_disable - Disable Pi-hole DNS blocking (with optional duration)
pihole_version - Get Pi-hole version information
pihole_test_connection - Test connection and authentication
The tool automatically detects your Pi-hole's API version:
Legacy Pi-hole: Uses /admin/api.php endpoint with API key authentication
Modern Pi-hole: Uses /api/* endpoints with web password authentication
The detection process:
Attempts to connect to modern API endpoints
Falls back to legacy API if modern endpoints are not available
Stores the detected version for future use
Credentials are stored securely using:
System Keyring (preferred): Uses your OS's secure credential storage
Encrypted File (fallback): AES-encrypted file in ~/.local/share/pihole-mcp-server/
By default, configuration is stored in:
Linux/macOS: ~/.local/share/pihole-mcp-server/
Windows: %LOCALAPPDATA%\pihole-mcp-server\
You can override this with the --config-dir option.
Variable | Description | Default |
| Configuration directory |
|
The Pi-hole MCP server implements a robust multi-layered security architecture to protect your Pi-hole authentication credentials. The credential manager uses a security-first approach with automatic fallback mechanisms to ensure your sensitive information remains protected across all supported platforms.
Primary Security Layer: The system first attempts to store credentials in your operating system's native keyring service, which provides hardware-backed encryption when available. On Linux, this integrates with GNOME Keyring, KDE Wallet, or Secret Service API. On macOS, credentials are stored in the secure Keychain. On Windows, the Windows Credential Manager is used. These system keyrings provide the highest level of security as they leverage your OS's built-in credential protection mechanisms.
Fallback Security Layer: If the system keyring is unavailable or fails, the credential manager automatically falls back to AES-256 encrypted file storage. This uses PBKDF2 key derivation (100,000 iterations) with SHA-256 hashing and machine-specific salts derived from your system's unique identifiers (machine ID, hostname, and username). The encrypted credentials are stored in restrictive-permission files (600/700) in your user's local configuration directory.
Platform-Specific Secure Storage Locations:
Linux: System keyring first, then ~/.local/share/pihole-mcp-server/credentials.json (encrypted)
macOS: macOS Keychain first, then ~/.local/share/pihole-mcp-server/credentials.json (encrypted)
Windows: Windows Credential Manager first, then %LOCALAPPDATA%\pihole-mcp-server\credentials.json (encrypted)
Users can verify their secure credential storage by checking their system's credential manager (Keychain Access on macOS, Credential Manager on Windows, or secret-tool on Linux) for entries under the service name "pihole-mcp-server", or by locating the encrypted backup file in their platform-specific configuration directory.
API keys and web passwords are never logged or displayed in plain text
Automatic detection prevents credential type mismatches
Memory-safe credential handling with immediate cleanup
Machine-specific encryption keys prevent credential portability attacks
Full HTTPS support with certificate verification
Option to disable SSL verification for self-signed certificates
Secure connection handling with proper timeout management
Configuration files use restrictive permissions (600/700)
No sensitive data in command line arguments
Secure credential prompting
Connection Failed
# Test your connection
pihole-mcp-cli test
# Check your Pi-hole is accessible
ping your-pihole-ip
# Test legacy Pi-hole API
curl http://your-pihole-ip/admin/api.php
# Test modern Pi-hole API
curl http://your-pihole-ip:8080/api/stats/summaryAuthentication Failed
For Legacy Pi-hole:
# Verify API key in Pi-hole admin interface
# Settings ā API / Web interface ā Show API token
# Re-login with correct API key
pihole-mcp-cli logout
pihole-mcp-cli login --host your-pihole-ip --api-key YOUR_API_KEYFor Modern Pi-hole:
# Use your web interface password (not API key)
pihole-mcp-cli logout
pihole-mcp-cli login --host your-pihole-ip --port 8080 --web-password YOUR_PASSWORDWrong Authentication Method
# If you get "unauthorized" errors, try the other authentication method
# Modern Pi-hole (usually port 8080) uses web password
# Legacy Pi-hole (usually port 80) uses API key
# Check which API version your Pi-hole uses
curl -I http://your-pihole-ip:8080/api/stats/summary # Modern
curl -I http://your-pihole-ip/admin/api.php # LegacyMCP Server Not Responding
# Test MCP server directly
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | pihole-mcp-server
# Check if credentials are configured
pihole-mcp-cli infoFor debugging, you can run the MCP server with logging:
# Enable debug logging
export PYTHONPATH=src
python -m pihole_mcp_server.server# Remove all stored credentials and configuration
pihole-mcp-cli logout
rm -rf ~/.local/share/pihole-mcp-server/# Clone the repository
git clone https://github.com/brettbergin/pihole-mcp-server.git
cd pihole-mcp-server
# Install development dependencies
uv sync --dev
# Install pre-commit hooks
pre-commit install
# Run tests
pytest
# Type checking
mypy src/
# Code formatting
black src/
isort src/pihole-mcp-server/
āāā src/pihole_mcp_server/
ā āāā __init__.py
ā āāā cli.py # Command-line interface
ā āāā credential_manager.py # Secure credential storage
ā āāā pihole_client.py # Pi-hole API client
ā āāā server.py # MCP server implementation
āāā tests/ # Test suite
āāā pyproject.toml # Project configuration
āāā README.md # This fileFork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Pi-hole - Network-wide ad blocking
Model Context Protocol - AI assistant integration
Cursor - AI-powered code editor
š Bug Reports: GitHub Issues
š” Feature Requests: GitHub Discussions
š Documentation: GitHub Wiki
Made with ā¤ļø for the Pi-hole and AI assistant communities
Disable Pi-hole DNS blocking
| Name | Required | Description | Default |
|---|---|---|---|
| duration_minutes | No | Duration in minutes to disable Pi-hole (optional, permanent if not specified) | |
| duration_seconds | No | Duration in seconds to disable Pi-hole (optional, overrides minutes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavior. Only states 'disable' without explaining impact (e.g., permanent vs temporary, effect on clients, or required permissions). Lacks disclosure of mutation or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no fluff. Highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with well-documented parameters in schema, but lacks description of return values or post-conditions. No output schema, so more context on response would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds no parameter info beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description 'Disable Pi-hole DNS blocking' clearly states the verb (disable) and the resource (Pi-hole DNS blocking). It is distinct from sibling tools like pihole_enable and pihole_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, such as when to specify a duration versus leaving it permanent. The description omits context for choosing parameters or distinguishing from pihole_enable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable Pi-hole DNS blocking
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fails to disclose any behavioral traits (e.g., idempotency, side effects, permissions required). With no annotations provided, the agent receives no information about what happens upon invocation or potential state changes beyond the generic verb 'enable'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. However, it may be too terse for an agent to fully understand the tool's behavior without additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description covers the basic purpose but lacks details on return values, error conditions, or behavioral nuances that an agent might need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. The description adds no parameter-level detail because there are none, which is acceptable but not informative. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Enable') and the resource ('Pi-hole DNS blocking'), directly conveying the tool's purpose. It distinguishes from siblings like pihole_disable (opposite) and pihole_status (status check).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The context of sibling tools implies complementary usage with pihole_disable, but the description lacks direct instructions on when to enable versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Pi-hole status and statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits such as read-only nature, rate limits, or authentication needs. Only states it returns status and statistics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Perfectly concise for a simple status tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, no-output-schema tool, the description is adequate but minimal. It doesn't specify what statistics are included, which could be helpful for an agent to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description adds no parameter information. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get Pi-hole status and statistics', which is a specific verb-resource combination. It distinguishes from siblings like disable, enable, test_connection, and version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It simply describes what it does without providing context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test Pi-hole connection and authentication
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It only says 'Test' without disclosing side effects, return format, or failure behavior. As a test tool, it likely has no destructive effects, but this is not confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple test tool with no parameters or output schema, but could mention what the response contains (e.g., success/failure) to fully inform an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100% trivially. Description adds no parameter info, which is acceptable for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Test Pi-hole connection and authentication', which is a specific verb+resource. It clearly distinguishes from sibling tools like pihole_status (status check) and pihole_version (version info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. The context suggests it's a preliminary test before other operations, but the description does not state prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Pi-hole version information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation with no side effects, which is adequate for a simple query. However, it does not detail the exact information returned (e.g., version format).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description adequately covers the tool's purpose. It could be more specific about the version format, but it is functionally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description does not need to add meaning beyond the schema. A baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Pi-hole version information', distinguishing it from sibling tools like pihole_disable or pihole_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Siblings have different purposes, but the description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.1pihole_disablepihole_enablepihole_statuspihole_test_connectionpihole_versionEach tool has a clearly distinct purpose: disable, enable, status, test connection, and version. No overlap in functionality.
All tools follow the pihole_ prefix with a consistent verb or noun pattern (disable, enable, status, test_connection, version). Naming is uniform and predictable.
5 tools is well-scoped for a Pi-hole server covering core operations. Not too few or too many for the domain.
Covers essential enable/disable/status/version operations. Missing detailed statistics or query list, but these are not critical for a basic management server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Control your Tesla from your AI assistant - climate, charging, access, and security.
Manage digital signage screens, playlists and media from your AI assistant.
Your Nightscout glucose data, conversational.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/brettbergin/pihole-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
