PI API MCP 서버

PI 대시보드 API와 상호 작용하기 위한 표준화된 도구와 리소스를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 구현을 통해 Claude를 비롯한 MCP 호환 AI 비서가 범주 및 차트를 포함한 PI 대시보드 리소스에 안전하게 액세스하고 관리할 수 있습니다.

MCP와 함께 PI 활용

다음은 설치 완료 후 MCP 서버의 일반적인 사용 시나리오를 보여줍니다.

초기 인증:

다음 지침을 실행하여 연결을 설정하세요.

지엑스피1

차트 분석:

차트 ID 450에 메타데이터 정보가 포함되어 있는 경우 다음 프롬프트를 사용하세요.

Retrieve the metadata from chart ID 450
Extract the chart JSON data from ID 450
Identify chart IDs associated with claims
Obtain JSON data for the identified charts
Analyze the data to generate actionable insights

출력 예:

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 pi-api-mcp-server를 자동으로 설치하려면:

npx -y @smithery/cli install @mingzilla/pi-api-mcp-server --client claude

설치 - Docker 사용(권장)

MCP 서버 구성이 필요하지 않습니다.
MCP 클라이언트 구성 파일 설정:

{
  "mcpServers": {
    "pi-api": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_URL=http://localhost:8224/pi/api/v2",
        "-e",
        "PI_API_KEY=XXXXXXXX",
        "mingzilla/pi-api-mcp-server"
      ],
      "disabled": false,
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts", 
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

중요 참고 사항 : 초기화 시 --api-url 매개변수를 지정하지 않으면 서버는 작업을 실행하기 전에 set-api-url 도구를 사용하여 API URL을 설정하라는 메시지를 표시합니다. 이러한 설계는 시작 시 URL이 미리 결정되지 않은 환경에서도 유연한 구성을 가능하게 합니다.

구성 파일 위치

Claude for Desktop 애플리케이션 구성은 다음에서 확인하세요.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: 지금은 다른 도구를 사용하세요. 예: Cline - MCP 구성 파일을 보여달라고 요청하세요.

사용 가능한 도구

스키마 검색

get-filterable-attributes : 샘플 엔터티를 조사하여 필터링에 사용할 수 있는 속성 목록을 가져옵니다.
Get the filterable attributes for chart entities

연결 관리

check-connection : 현재 API URL과 인증이 유효한지 확인합니다.
set-api-url : 모든 요청에 대한 기본 API URL을 구성합니다.
Set the API URL to http://localhost:8224/pi/api/v2

입증

인증 : 인증 옵션에 대한 안내를 받으세요
authenticate-with-credentials : 사용자 이름과 비밀번호로 인증(최후의 수단)
keep-session-alive : 현재 인증 토큰을 확인하고 새로 고칩니다(토큰 기반 인증에도 사용됨)
logout : 현재 토큰을 무효화하고 세션을 종료합니다.
set-organization : 후속 요청에 대한 조직 ID를 설정합니다.

차트

list-charts : 필터링을 지원하는 모든 차트를 나열합니다.
get-chart : ID로 차트 가져오기
delete-chart : 차트 삭제
export-chart : 다양한 형식으로 차트를 내보냅니다.

사용 가능한 리소스

auth://status : 인증 상태 가져오기
Categories://list : 모든 카테고리를 나열합니다
Categories://{id} : 특정 카테고리 가져오기
Categories://{categoryId}/objects : 특정 카테고리에 대한 객체를 가져옵니다.
charts://list : 모든 차트를 나열합니다
charts://{id} : 특정 차트 가져오기
charts://{id}/export/{format} : 특정 형식으로 차트를 내보냅니다.

사용 가능한 프롬프트

분석-카테고리 : 대시보드의 카테고리 분석
analyze-charts : 대시보드에서 차트 분석
compare-charts : 두 차트 간의 데이터를 비교합니다
category-usage-analysis : 차트에서 카테고리가 어떻게 사용되는지 분석합니다.
use-filters : 이 API를 사용하여 필터를 효과적으로 사용하는 방법을 보여줍니다.

클로드 적분 예제

서버에 연결한 후 Claude와 함께 사용할 수 있는 몇 가지 쿼리 예는 다음과 같습니다.

API URL 설정

Please use the set-api-url tool to set the PI API URL to http://localhost:8224/pi/api/v2

입증

Please help me authenticate to the PI API.

I have a token. Please use the keep-session-alive tool with my token: [YOUR_TOKEN_HERE]

Please check if my connection to the PI API is working properly.

카테고리 작업

List all categories in the dashboard.

Get details about category with ID 123.

차트 작업

List all the charts available in the dashboard.

Export chart with ID 456 as a PDF.

필터 사용

Get the filterable attributes for chart entities to understand what fields I can filter on.

List charts with description containing "revenue" using the filter option.

분석 프롬프트 사용

Analyze the categories in the dashboard.

Compare data between charts 123 and 456.

Show me how to use filters effectively with this API.

개발

로컬 실행

참고: start.sh 사용하여 개발 서버를 실행할 수도 있습니다.

# Clone the repository (SSH or HTTPS option)
git clone git@github.com:mingzilla/pi-api-mcp-server.git
cd pi-api-mcp-server

# Install dependencies
npm install
./dependencies.sh # Installs global dependencies to enable MCP client connection via "@mingzilla/pi-api-mcp-server"

# Build the project
npm run build

# Execute the server
npm start

NPM 설치

# Global installation
npm install -g @mingzilla/pi-api-mcp-server

# Direct execution via npx
npx @mingzilla/pi-api-mcp-server --api-url "http://localhost:8224/pi/api/v2" --auth-token "XXXXXXXX"

MCP 클라이언트 구성

데스크톱용 Claude와 통합:

Node.js 구현

"로컬 실행" 섹션의 지침을 실행하세요.
필수 종속성을 설치하기 위해 ./dependencies.sh 실행되었는지 확인하세요.
다음 구성을 구현합니다(참고: "@mingzilla/pi-api-mcp-server"는 "로컬 실행"을 통해 설치된 패키지를 참조합니다)

{
  "mcpServers": {
    "pi-api": {
      "command": "npx",
      "args": [
        "-y",
        "@mingzilla/pi-api-mcp-server",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

지역 개발

./start.sh 사용하여 서버를 실행합니다.
build/index.js 파일에 대한 경로로 구성을 설정합니다.

./start.sh

{
  "mcpServers": {
    "pi-api": {
      "command": "node",
      "args": [
        "/home/mingzilla/dev/tool-mcp-pi-api-server/build/index.js",
        "--api-url",
        "http://localhost:8224/pi/api/v2",
        "--auth-token",
        "XXXXXXXX"
      ],
      "autoApprove": [
        "keep-session-alive",
        "check-connection",
        "authenticate",
        "list-categories",
        "get-category",
        "list-charts",
        "get-chart",
        "export-chart",
        "get-filterable-attributes",
        "export-chart"
      ]
    }
  }
}

개발 체크리스트

코드 업데이트 -> 로컬 서버 시작 -> index.js 파일 경로로 로컬 서버 테스트
readme.md 파일 업데이트 -> mcpServers 구성 섹션 변경: docker + node + npx
./publish.sh - npm에 게시
./dockerBuild.sh -> ./dockerPublish.sh (package.json과 일치하도록 버전 번호 편집) -> docker config 테스트
코드를 github에 푸시하세요

특허

MIT 라이센스

작가

밍 황(mingzilla)

PI API MCP Server

Integrations