Pi-hole MCP Server

An MCP (Model Context Protocol) server for controlling Pi-hole ad blocking.

Note: This server is configured for Pi-hole v6 with REST API authentication using app passwords.

Configuration

The server uses a config.json file for configuration. Create this file in the project root:

Configuration Options

• server.mode: Server mode - "stdio" (default) or "port"

• server.port: Port number when using port mode (default: 5000)

• pihole.base_url: Pi-hole API base URL (default: "http://192.168.68.59:8081/api")

Setup

1. Ensure your Pi-hole has an app password configured (Settings > API > App Password)

2. Set the environment variable with your app password:

   export PIHOLE_APP_PASSWORD=your_app_password_here

3. Configure the server mode in config.json

Running

Stdio Mode (Default)

Run the server in stdio mode (for MCP clients):

Port Mode

Set "mode": "port" in config.json and run:

The server will start on the configured port (default: 5000) using Server-Sent Events (SSE).

Or use the VS Code task: Ctrl+Shift+P > Tasks: Run Task > Run Python Script

Running with Docker

Prerequisites

• Docker and Docker Compose installed

• Pi-hole app password configured

Setup

1. Ensure your config.json is configured for your environment

2. Set the Pi-hole app password as an environment variable:

   export PIHOLE_APP_PASSWORD=your_app_password_here

Running

Configuration

The container uses the config.json file mounted as a volume. You can modify the configuration file and restart the container:

Logs

Cleanup

Tools

• get_pihole_status: Get current Pi-hole blocking status (enabled/disabled)

• get_pihole_summary: Get Pi-hole statistics summary (queries, blocked domains, etc.)

• enable_pihole: Enable ad blocking permanently

• disable_pihole: Disable ad blocking (optional duration in seconds)

API Details

This implementation uses Pi-hole v6 REST API with session-based authentication:

• Authentication: POST to /api/auth with app password

• Status: GET /api/dns/blocking

• Summary: GET /api/stats/summary

• Control: POST to /api/dns/blocking with JSON payload

Testing

Run unit tests (mocked):

Run configuration tests:

Run integration tests (requires PIHOLE_APP_PASSWORD and will actually control Pi-hole):

Warning: Integration tests will enable/disable Pi-hole blocking. Use with caution!

Debugging

Open main.py, press F5 or use the Run and Debug panel.