brettbergin/pihole-mcp-server

Pi-hole MCP Server

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.

Features

• 🔐 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

Installation

Prerequisites

• 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 from PyPI (Recommended)

# Install globally to ~/.local/
pip install --user pihole-mcp-server

# Or using uv
uv tool install pihole-mcp-server

Install from Source

# 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 .

Quick Start

1. Configure Pi-hole Credentials

First, you need to authenticate with your Pi-hole instance:

pihole-mcp-cli login

The 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

Manual Authentication Method Selection

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 -

2. Test Your Connection

pihole-mcp-cli test

3. Use with Cursor or Other MCP Clients

Add the following to your Cursor MCP configuration:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp-server",
      "args": []
    }
  }
}

4. Start Managing Pi-hole with AI

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?"

CLI Usage

Available Commands

Login Command Options

Examples

# 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 --help

MCP Tools

The MCP server provides the following tools for AI assistants:

Core Operations

• 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)

Statistics and Analytics

System Information

• pihole_version - Get Pi-hole version information
• pihole_test_connection - Test connection and authentication

Configuration

API Version Detection

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:

1. Attempts to connect to modern API endpoints
2. Falls back to legacy API if modern endpoints are not available
3. Stores the detected version for future use

Credential Storage

Credentials are stored securely using:

1. System Keyring (preferred): Uses your OS's secure credential storage
2. Encrypted File (fallback): AES-encrypted file in ~/.local/share/pihole-mcp-server/

Configuration Directory

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.

Environment Variables

Security

Credential Protection Architecture

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.

Additional Security Features

• 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

SSL/TLS Support

• Full HTTPS support with certificate verification
• Option to disable SSL verification for self-signed certificates
• Secure connection handling with proper timeout management

Permissions

• Configuration files use restrictive permissions (600/700)
• No sensitive data in command line arguments
• Secure credential prompting

Troubleshooting

Common Issues

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/summary

Authentication 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_KEY

For 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_PASSWORD

Wrong 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          # Legacy

MCP 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 info

Debug Mode

For debugging, you can run the MCP server with logging:

# Enable debug logging
export PYTHONPATH=src
python -m pihole_mcp_server.server

Reset Configuration

# Remove all stored credentials and configuration
pihole-mcp-cli logout
rm -rf ~/.local/share/pihole-mcp-server/

Development

Setup Development Environment

# 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/

Project Structure

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 file

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Pi-hole - Network-wide ad blocking
• Model Context Protocol - AI assistant integration
• Cursor - AI-powered code editor

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📚 Documentation: GitHub Wiki

Made with ❤️ for the Pi-hole and AI assistant communities