Pi-hole MCP Server

Name: Pi-hole MCP Server
Author: ranklancer

by ranklancerversion 0.2.0i★ 3iRuns on your computer

Registry nameio.github.ranklancer/pihole-mcp

How to install

What it does

MCP server for Pi-hole v6 API — manage multiple instances: queries, lists, groups, stats

Connects Runs on your computer
Account or key Needs PIHOLE_PASSWORD · 2 settings to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL)
Category Other

Install

Pick the AI app you use, then copy the settings.

Passed 3/3 checks · Runs on your computer · ✓ Commands checked Nov 13, 2026

First: which AI do you use?

ClaudeWeb · app · phoneChatGPTWebClaude CodeTerminalCursorCode editorVS CodeCode editorOtherOther apps

Pick your app and the steps appear below.

Works with Claude, with some setup first

You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone

Install Node.js
One time only; it works for every server that needs Node.js
Open the Node.js download page ↗
Done
Sign up and create a Pi-hole MCP Server key
Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.
How to get a key is in the maker’s README below
Done
3
Fill in 2 setting(s)
These are program settings, not keys. No sign-up needed; fill them in as the maker describes.
- PIHOLE_INSTANCES Comma-separated list of Pi-hole instance names (e.g. 'pihole' or 'primary,secondary')
- PIHOLE_BASE_URL Base URL of your first Pi-hole instance (e.g. 'http://192.168.1.100')
Descriptions are as written by the maker.
Done
Open the Claude desktop app’s settings file
SettingsDeveloperEdit Config
Done

Paste these settings and save the file

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "-y",
        "@ranklancer/pihole-mcp"
      ],
      "env": {
        "PIHOLE_INSTANCES": "your-value",
        "PIHOLE_BASE_URL": "your-value",
        "PIHOLE_PASSWORD": "your-value"
      }
    }
  }
}

Paste the key only into the app’s field, never into a chat or to anyone

Done

Quit Claude and open it again
Done
Try it
Use Pi-hole MCP Server and tell me what you can do for me, then show me one thing
✓ If Claude says it is using Pi-hole MCP Server or shows a Pi-hole MCP Server tool in the answer, you are connected

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

ChatGPT cannot connect Pi-hole MCP Server yet

Pi-hole MCP Server runs on your computer, but ChatGPT can only connect servers that run on the web

What you can do instead

A · Use an app that can connect Pi-hole MCP Server

Steps for Claude →You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone
Steps for Claude Code →You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)
Steps for Cursor →You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)
Steps for VS Code →You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)

B · Others in Other that work with ChatGPT

Picked from the most used in the same category, only ones that connect by address with no key

Hostinger✓ ChatGPT
World Monitor✓ ChatGPT
Svelte MCP✓ ChatGPT

Works with Claude Code, with some setup first

You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)

Install Node.js
One time only; it works for every server that needs Node.js
Open the Node.js download page ↗
Done
Sign up and create a Pi-hole MCP Server key
Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.
How to get a key is in the maker’s README below
Done
3
Fill in 2 setting(s)
These are program settings, not keys. No sign-up needed; fill them in as the maker describes.
- PIHOLE_INSTANCES Comma-separated list of Pi-hole instance names (e.g. 'pihole' or 'primary,secondary')
- PIHOLE_BASE_URL Base URL of your first Pi-hole instance (e.g. 'http://192.168.1.100')
Descriptions are as written by the maker.
Done
Open Terminal
Mac: press Command+Space and type Terminal · Windows: open PowerShell
Done
5
Paste this command and press Enter
```
claude mcp add --scope user pihole --env PIHOLE_INSTANCES=your-value --env PIHOLE_BASE_URL=your-value --env PIHOLE_PASSWORD=your-value -- npx -y @ranklancer/pihole-mcp
```
Replace “your-value” with your key before pressing Enter
Paste the key only into the app’s field, never into a chat or to anyone
Done
Type /mcp in Claude Code
You should see Pi-hole MCP Server listed as connected
Done
Try it
Use Pi-hole MCP Server and tell me what you can do for me, then show me one thing
✓ If Claude Code says it is using Pi-hole MCP Server or shows a Pi-hole MCP Server tool in the answer, you are connected

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with Cursor, with some setup first

You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)

Install Node.js
One time only; it works for every server that needs Node.js
Open the Node.js download page ↗
Done
Sign up and create a Pi-hole MCP Server key
Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.
How to get a key is in the maker’s README below
Done
3
Fill in 2 setting(s)
These are program settings, not keys. No sign-up needed; fill them in as the maker describes.
- PIHOLE_INSTANCES Comma-separated list of Pi-hole instance names (e.g. 'pihole' or 'primary,secondary')
- PIHOLE_BASE_URL Base URL of your first Pi-hole instance (e.g. 'http://192.168.1.100')
Descriptions are as written by the maker.
Done
Click this button to open Cursor
Open in Cursor
Cursor asks you to confirm; click Install
Done
Fill in your key
In the Pi-hole MCP Server settings, PIHOLE_PASSWORD, PIHOLE_INSTANCES, PIHOLE_BASE_URL is empty; add your key and save
Paste the key only into the app’s field, never into a chat or to anyone
Done
Open the AI chat in Cursor in Agent mode
Done
Try it
Use Pi-hole MCP Server and tell me what you can do for me, then show me one thing
✓ If Cursor says it is using Pi-hole MCP Server or shows a Pi-hole MCP Server tool in the answer, you are connected

Menu names checked against Cursor’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with VS Code, with some setup first

You need a Pi-hole MCP Server key (create it on the maker’s site) · 2 setting(s) to fill in (PIHOLE_INSTANCES, PIHOLE_BASE_URL) · Install Node.js on your computer first (one time)

Install Node.js
One time only; it works for every server that needs Node.js
Open the Node.js download page ↗
Done
Sign up and create a Pi-hole MCP Server key
Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.
How to get a key is in the maker’s README below
Done
3
Fill in 2 setting(s)
These are program settings, not keys. No sign-up needed; fill them in as the maker describes.
- PIHOLE_INSTANCES Comma-separated list of Pi-hole instance names (e.g. 'pihole' or 'primary,secondary')
- PIHOLE_BASE_URL Base URL of your first Pi-hole instance (e.g. 'http://192.168.1.100')
Descriptions are as written by the maker.
Done
Click this button to open VS Code
Open in VS Code
VS Code asks you to confirm; click Install
Done
Fill in your key
In the Pi-hole MCP Server settings, PIHOLE_PASSWORD, PIHOLE_INSTANCES, PIHOLE_BASE_URL is empty; add your key and save
Paste the key only into the app’s field, never into a chat or to anyone
Done
Open the AI chat in VS Code in Agent mode
Done
Try it
Use Pi-hole MCP Server and tell me what you can do for me, then show me one thing
✓ If VS Code says it is using Pi-hole MCP Server or shows a Pi-hole MCP Server tool in the answer, you are connected

Menu names checked against VS Code’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Other apps that use MCP, such as Windsurf, Zed or Gemini CLI, each add servers differently. See how in the app list.

See every app that uses MCP →

JSON settings are under “For developers” below

Stuck? Ask people who use Pi-hole MCP Server💬 Discussion →

For developers: Terminal commands and JSON settings

Installed on your computer

Claude Code

claude mcp add --scope user pihole --env PIHOLE_INSTANCES=your-value --env PIHOLE_BASE_URL=your-value --env PIHOLE_PASSWORD=your-value -- npx -y @ranklancer/pihole-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "-y",
        "@ranklancer/pihole-mcp"
      ],
      "env": {
        "PIHOLE_INSTANCES": "your-value",
        "PIHOLE_BASE_URL": "your-value",
        "PIHOLE_PASSWORD": "your-value"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "-y",
        "@ranklancer/pihole-mcp"
      ],
      "env": {
        "PIHOLE_INSTANCES": "your-value",
        "PIHOLE_BASE_URL": "your-value",
        "PIHOLE_PASSWORD": "your-value"
      }
    }
  }
}

VS Code (mcp.json)

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ranklancer/pihole-mcp"
      ],
      "env": {
        "PIHOLE_INSTANCES": "your-value",
        "PIHOLE_BASE_URL": "your-value",
        "PIHOLE_PASSWORD": "your-value"
      }
    }
  }
}

Values you fill in

PIHOLE_INSTANCES required env
Comma-separated list of Pi-hole instance names (e.g. 'pihole' or 'primary,secondary')
PIHOLE_BASE_URL required env
Base URL of your first Pi-hole instance (e.g. 'http://192.168.1.100')
PIHOLE_PASSWORD secret required env
API password for your first Pi-hole instance

Descriptions are as written by the maker.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

At a glance

GitHub stars i: 3
Downloads per weeki: 32/wk
Licence i: MIT
Connection: Runs on your computer
Transport: stdio
Latest versioni: 0.2.0
Categoryi: Other
Published to registryi: Apr 12, 2026
Code last changedi: Nov 14, 2026
Maker: ranklancer
Packages: npm: @ranklancer/pihole-mcp
Repo: ranklancer/pihole-mcp
Registry status: Active

Which apps can use it

Based on how this server connects and on each app’s own docs, checked Nov 10, 2026.

Run on your computer in

Claude Goose LM Studio Msty Studio Cherry Studio Cursor VS Code + GitHub Copilot Visual Studio Windsurf (Devin Desktop)Zed Kiro Cline Continue JetBrains AI Assistant Claude Code Codex CLI Gemini CLI OpenCode nodecode Warp LibreChat Raycast

All apps, with pros and cons →

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 14, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account ranklancer, which owns the repo
✓ Pass
Still maintained
Code last changed today
✓ Pass
Has a licence
Uses MIT
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Discussion

Ask, share a tip or report that it does not work. Sorted by what people marked helpful.

No posts yet. Be the first to ask or share.

Posts here are written by users, not the PopNx team.

User reviews

No reviews yet

Compared with others in Otheri

More stars than 93% of the other 19754 servers in this category
Published to the registry more recently than 4% of the other 19754 servers in this category
Basic checks equal to or better than 100% of the other 19754 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Pi-hole MCP Server safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: PIHOLE_PASSWORD

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed today, and the latest version (0.2.0) reached the registry 7 months ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: World Monitor, Claude Flow, Windmill

Others in the same category

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

World Monitor

Real-time global intelligence on conflict, markets, energy, trade, shipping and cyber. 97 tools.

by koala73Widely used★ 90.6KUpdated yesterday

Runs in the cloud✓ service owner · worldmonitor.app

How to connect

Claude Flow

AI orchestration with hive-mind swarms, neural networks, and 87 MCP tools for enterprise dev.

by ruvnetWidely used↓ 13.5K/wk★ 81.7KUpdated 14 months ago

Runs on your computer

Install

Windmill

Run Windmill scripts and flows and manage jobs, schedules, resources and variables.

by windmill-labsWidely used★ 18.6KUpdated 2 days ago

Runs in the cloud

How to connect

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

pihole-mcp

An MCP (Model Context Protocol) server that gives AI assistants like Claude full control over your Pi-hole v6 DNS ad-blocker - query logs, allow/deny lists, group management, gravity reload, and stats. Designed from day one for multi-instance deployments: manage one or many Pi-hole instances from a single MCP endpoint.

Why?

Pi-hole's admin API is powerful but cumbersome to script against. This MCP server turns every Pi-hole API action into a tool that any MCP-compatible AI assistant can call directly. Instead of clicking through the admin UI or writing curl commands, just ask your AI to check what's being blocked, allowlist a domain, or compare stats across instances.

Perfect for homelabbers running multiple Pi-holes (primary + secondary, or per-VLAN), network admins managing DNS filtering at scale, and anyone who wants AI-assisted DNS management.

Features

Multi-instance support - configure 1 to N Pi-hole instances via environment variables
Full Pi-hole v6 API coverage - query logs, allow/deny lists (full CRUD), group and client management, blocking control, local DNS (A + CNAME) records, gravity reload, stats
Smart regex detection - automatically routes domains to exact or regex lists based on metacharacter analysis
Regex landmine detector - finds deny-exact entries that look like they should be regex (miscategorized rules)
Docker-ready - multi-stage Dockerfile with non-root user, health checks, and security hardening
Streamable HTTP or stdio transport - run as a long-lived HTTP service, or let the MCP client spawn it on demand
Docker secrets support - passwords via env vars or /run/secrets/ files

Quick Start

Docker (recommended)

git clone https://github.com/ranklancer/pihole-mcp.git

cd pihole-mcp cp .env.example .env

Edit .env with your Pi-hole URL(s) and password(s)

mkdir -p secrets echo "your-pihole-password" > secrets/pihole_password chmod 600 secrets/pihole_password

cp docker-compose.example.yml docker-compose.yml docker compose up -d

Node.js

npm install

npm run build export PIHOLE_INSTANCES=pihole export PIHOLE_BASE_URL=http://pihole.example.com export PIHOLE_PASSWORD=your-password npm start

Local on demand (stdio, no Docker)

The MCP client starts the server as a child process when needed and talks to it over stdin/stdout. No port is opened and nothing keeps running in the background.

npm ci

npm run build cp .env.example .env chmod 600 .env

Edit .env with your Pi-hole URL(s) and password(s)

claude mcp add --scope user pihole -- bash -c \

'set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js'

Or add it manually to your MCP client config:

"mcpServers": { "pihole": { "type": "stdio", "command": "bash", "args": ["-c", "set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js"] } } }

HOST and PORT from .env are ignored in stdio mode.

Configuration

All configuration is via environment variables. See .env.example for the full reference.

Single Instance

PIHOLE_INSTANCES=pihole

PIHOLE_BASE_URL=http://192.0.2.100 PIHOLE_PASSWORD=your-password

Multiple Instances

PIHOLE_INSTANCES=primary,secondary

PRIMARY_BASE_URL=http://192.0.2.100 PRIMARY_PASSWORD=password1 SECONDARY_BASE_URL=https://198.51.100.101 SECONDARY_PASSWORD=password2 SECONDARY_INSECURE_TLS=true

For each instance name in PIHOLE_INSTANCES, provide:

Variable	Required	Description
`_BASE_URL`	Yes	Pi-hole base URL (e.g. `http://pihole.local`)
`_PASSWORD`	Yes	Pi-hole API password (or use Docker secrets)
`_INSECURE_TLS`	No	Set `true` for self-signed certs (default: `false`)

Docker secrets are supported as a fallback: /run/secrets/ _password (lowercase).

Available MCP Tools

Tool	Description
`pihole_query_log`	Fetch query log with filters (limit, time range, client IP or name, domain, status)
`pihole_allow_domain`	Add to allowlist (auto-detects exact vs regex)
`pihole_deny_domain`	Add to denylist (auto-detects exact vs regex)
`pihole_list_allowlist`	List all allowlist entries (exact + regex merged)
`pihole_list_denylist`	List all denylist entries (exact + regex merged)
`pihole_stats_summary`	Get Pi-hole statistics summary
`pihole_reload_lists`	Trigger gravity reload
`pihole_group_management`	CRUD operations on Pi-hole groups
`pihole_client_management`	CRUD operations on Pi-hole clients and their group assignments
`pihole_check_regex_types`	Detect miscategorized regex in deny-exact list
`pihole_set_blocking`	Enable/disable blocking, with optional auto-revert timer
`pihole_domain_management`	Update or delete an allow/deny domain (completes CRUD)
`pihole_local_dns`	List/add/delete local DNS A records
`pihole_local_cname`	List/add/delete local CNAME records

Every tool accepts an optional instance parameter to target a specific Pi-hole. Defaults to the first configured instance.

Connecting to Your MCP Client

This section applies to the HTTP transport (Docker or npm start). For stdio, see Local on demand.

The server listens on http://HOST:PORT/mcp (default: http://localhost:3000/mcp). The HTTP endpoint has no authentication, so keep it bound to localhost or a trusted network.

Claude Desktop / Claude Code

Add to your MCP settings:

"mcpServers": { "pihole": { "url": "http://localhost:3031/mcp" } } }

Health Check

curl http://localhost:3031/health

{"ok":true,"service":"pihole-mcp","version":"0.3.0"}

Development

npm install

npm run dev # Watch mode — recompiles on save npm start # Run the server

Requirements

Node.js >= 20
Pi-hole v6 with API access enabled
Network connectivity to your Pi-hole instance(s)

Related Projects

Pi-hole — Network-wide ad blocking
Model Context Protocol — Open standard for AI tool integration
MCP Server Registry — Directory of MCP servers

License

MIT

Pi-hole MCP Server

What it does

Install

Install Node.js

Sign up and create a Pi-hole MCP Server key

Fill in 2 setting(s)

Open the Claude desktop app’s settings file

Paste these settings and save the file

Quit Claude and open it again

Try it

What you can do instead

Install Node.js

Sign up and create a Pi-hole MCP Server key

Fill in 2 setting(s)

Open Terminal

Paste this command and press Enter

Type /mcp in Claude Code

Try it

Install Node.js

Sign up and create a Pi-hole MCP Server key

Fill in 2 setting(s)

Click this button to open Cursor

Fill in your key

Open the AI chat in Cursor in Agent mode

Try it

Install Node.js

Sign up and create a Pi-hole MCP Server key

Fill in 2 setting(s)

Click this button to open VS Code

Fill in your key

Open the AI chat in VS Code in Agent mode

Try it

Installed on your computer

Values you fill in

At a glance

Which apps can use it

Related guides

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Discussion

User reviews

Compared with others in Otheri

Common questions

Others in the same category

World Monitor

Claude Flow

Windmill

README from the maker

pihole-mcp

Why?

Features

Quick Start

Docker (recommended)

Edit .env with your Pi-hole URL(s) and password(s)

Node.js

Local on demand (stdio, no Docker)

Edit .env with your Pi-hole URL(s) and password(s)

Configuration

Single Instance

Multiple Instances

Available MCP Tools

Connecting to Your MCP Client

Claude Desktop / Claude Code

Health Check

{"ok":true,"service":"pihole-mcp","version":"0.3.0"}

Development

Requirements

Related Projects

License