pihole-mcp

MCP(Model Context Protocol) 서버로, Claude와 같은 AI 어시스턴트가 Pi-hole v6 DNS 광고 차단기를 완전히 제어할 수 있게 해줍니다 - 로그 조회, 허용/차단 목록, 그룹 관리, gravity 리로드, 통계 등. 처음부터 다중 인스턴스 배포를 염두에 두고 설계되었습니다: 단일 MCP 엔드포인트에서 하나 또는 여러 Pi-hole 인스턴스를 관리할 수 있습니다.

왜 필요한가?

Pi-hole의 관리 API는 강력하지만 스크립트로 다루기에는 번거롭습니다. 이 MCP 서버는 모든 Pi-hole API 작업을 MCP 호환 AI 어시스턴트가 직접 호출할 수 있는 도구로 변환합니다. 관리 UI를 클릭하거나 curl 명령을 작성하는 대신, AI에게 차단된 항목을 확인하거나 도메인을 허용 목록에 추가하거나 인스턴스 간 통계를 비교하도록 요청하면 됩니다.

여러 Pi-hole(기본 + 보조, 또는 VLAN별)을 운영하는 홈랩 사용자, 대규모 DNS 필터링을 관리하는 네트워크 관리자, AI 지원 DNS 관리를 원하는 모든 사람에게 적합합니다.

Related MCP server: MCP Pi-hole Server

기능

• 다중 인스턴스 지원 - 환경 변수를 통해 1~N개의 Pi-hole 인스턴스 구성

• Pi-hole v6 API 전체 지원 - 로그 조회, 허용/차단 목록(전체 CRUD), 그룹 관리, 차단 제어, 로컬 DNS(A + CNAME) 레코드, gravity 리로드, 통계

• 스마트 정규식 감지 - 메타문자 분석을 기반으로 도메인을 정확(exact) 또는 정규식(regex) 목록으로 자동 라우팅

• 정규식 지뢰 탐지기 - 정규식처럼 보이지만 정확(deny-exact) 목록에 잘못 분류된 항목을 찾아냄

• Docker 준비 완료 - 다단계 Dockerfile, 비루트 사용자, 헬스 체크, 보안 강화

• 스트리밍 HTTP 전송 - HTTP 기반 MCP를 지원하는 모든 MCP 클라이언트와 호환

• Docker secrets 지원 - 환경 변수 또는 /run/secrets/ 파일을 통한 비밀번호

빠른 시작

Docker(권장)

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

구성

모든 구성은 환경 변수를 통해 이루어집니다. 전체 참조는 .env.example을 참조하세요.

단일 인스턴스

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

다중 인스턴스

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

PIHOLE_INSTANCES의 각 인스턴스 이름에 대해 다음을 제공하세요:

Docker secrets는 대체 수단으로 지원됩니다: /run/secrets/<name>_password (소문자).

사용 가능한 MCP 도구

모든 도구는 특정 Pi-hole을 대상으로 하는 선택적 instance 매개변수를 허용합니다. 기본값은 첫 번째 구성된 인스턴스입니다.

MCP 클라이언트에 연결

서버는 http://HOST:PORT/mcp에서 수신합니다 (기본값: http://localhost:3000/mcp).

Claude Desktop / Claude Code

MCP 설정에 추가:

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

Supergateway (stdio 래퍼)

MCP 클라이언트가 stdio 전송만 지원하는 경우 supergateway를 사용하세요:

npx -y supergateway --streamableHttp http://localhost:3031/mcp

헬스 체크

curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.3.0"}

개발

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

요구 사항

• Node.js >= 20

• API 액세스가 활성화된 Pi-hole v6

• Pi-hole 인스턴스에 대한 네트워크 연결

관련 프로젝트

• Pi-hole — 네트워크 전체 광고 차단

• Model Context Protocol — AI 도구 통합을 위한 개방형 표준

• MCP Server Registry — MCP 서버 디렉토리

라이선스

MIT