Pi-hole MCP Server

🍓 피홀-MCP-세러

Pi-hole용 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 AI 비서가 사용할 수 있는 도구로서 Pi-hole 기능을 제공합니다.

종속성

도커

• Docker 설치 가이드

uv (선택 사항, 개발용)

애플리케이션을 로컬에서 실행하려면 uv 사용하세요. 원하는 패키지 관리자를 사용하여 설치하세요.

환경

Pi-hole 자격 증명을 사용하여 프로젝트 루트에 .env 파일을 만듭니다.

지엑스피1

프로젝트 구조

이 프로젝트는 보다 나은 유지 관리를 위해 모듈식 조직을 따릅니다.

이 구조는 모든 실행 모드와의 호환성을 유지하면서 코드를 논리적 구성 요소로 분리합니다.

서버 실행

Pi-hole MCP 서버를 실행하는 방법에는 여러 가지가 있습니다.

Docker 사용(프로덕션에 권장)

서버는 http://localhost:8383 에서 사용할 수 있습니다.

Docker를 사용한 개발 모드

개발의 경우 로컬로 빌드되는 dev compose 파일을 사용하세요.

MCP 검사관

uv 와 mcp CLI를 사용하여 MCP 검사기를 실행할 수 있습니다.

이렇게 하면 http://localhost:6274 에서 도구와 리소스를 테스트할 수 있는 대화형 인터페이스가 시작됩니다.

API

이 MCP 서버는 다음과 같은 리소스와 도구를 제공합니다.

자원

• piholes:// : 구성된 모든 Pi-hole에 대한 정보를 반환합니다.
• version:// : MCP 서버 버전을 반환합니다.
• list-tools:// : 도구 범주 목록을 반환합니다.
  • list-tools://{category} : 특정 카테고리 내 도구 목록을 반환합니다.

도구

각 도구 호출은 다음 구조의 사전 목록으로 결과를 반환합니다.

구성

• list_local_dns : Pi-hole의 모든 로컬 DNS 설정을 나열합니다.
• add_local_a_record : Pi-hole에 로컬 A 레코드를 추가합니다.
• add_local_cname_record : Pi-hole에 로컬 CNAME 레코드를 추가합니다.
• remove_local_a_record : 호스트 이름에 대한 모든 A 레코드를 제거합니다.
• remove_local_cname_record : 호스트 이름에 대한 모든 CNAME 레코드를 제거합니다.

메트릭

• list_queries : Pi-hole에서 최근 DNS 쿼리 기록을 가져옵니다.
• list_query_suggestions : 쿼리 필터 제안 받기
• list_query_history : 시간 경과에 따른 쿼리에 대한 활동 그래프 데이터 가져오기

goose 테스트

Goose는 테스트 및 개발에 유용한 CLI LLM 클라이언트입니다. 여기에서 설치 지침을 확인하세요.

다음 내용은 goose configure 사용하여 초기 설정을 완료했다고 가정합니다.

확장 프로그램 구성

1. goose configure 입력하여 구성 메뉴를 엽니다.
2. 확장 프로그램 추가를 선택하세요
3. 원격 확장 프로그램 선택
4. 이름을 입력하라고 하는데, 뭐라 부르든 상관없어요. 저는 pihole-mcp 라고 이름 지었어요.
5. "SSE 엔드포인트 URI는 무엇입니까?"라는 질문이 나오면 http://localhost:8383/sse 입력합니다.
6. 시간 초과를 입력하세요.
7. 원하시면 설명을 추가하세요.
8. 환경 변수에 대한 질문이 나오면 아니요를 선택하세요.

세션 시작

서버가 설치되면 채팅 세션을 시작하세요.

"내 로컬 DNS 레코드는 무엇인가?" 라고 질문해보세요.

...또는 "최근 DNS 쿼리를 보여주세요." 라고 말합니다.

클로드 데스크탑

Claude의 데스크톱 클라이언트는 현재 STDIO 프로토콜만 지원하지만, 프록시를 사용하여 SSE 엔드포인트와 통신할 수 있습니다.

claude_desktop_config.json 파일에 다음을 추가하세요.

로컬 네트워크의 다른 호스트에 연결하고 보안되지 않은 연결을 사용하는 경우, --allow-http 인수를 사용하여 해당 연결을 명시적으로 허용해야 합니다. 예:

그런 다음 애플리케이션을 완전히 재시작하고 사용해보세요.

특허

MIT