PowerBI MCP Server

Microsoft Power BI와 Azure AD API를 통한 통합을 위한 완전한 기능의 Model Context Protocol (MCP) 서버입니다.

🎯 기능

📖 READ 작업 (7개 도구):

• get_workspaces - 사용 가능한 모든 workspace 목록 가져오기

• get_datasets - datasets 목록 가져오기 (workspace별 필터링 가능)

• get_reports - 보고서 목록 가져오기 (workspace별 필터링 가능)

• get_dataset_tables - dataset 테이블 구조 가져오기

• query_dataset - dataset에 DAX 쿼리 실행

• refresh_dataset - dataset 새로고침 실행

• get_refresh_history - dataset 새로고침 기록 가져오기

🏗️ WORKSPACE 관리 (3개 도구):

• create_workspace - 새 workspace 생성

• delete_workspace - workspace 삭제

• add_workspace_user - 액세스 권한이 있는 사용자 추가

📊 DATASET 관리 (3개 도구):

• create_dataset - 테이블과 스키마가 있는 datasets 생성

• delete_dataset - datasets 삭제

• update_dataset - datasets 구성 업데이트

🗃️ TABLE 관리 (3개 도구):

• create_table - datasets에 테이블 생성

• delete_table - 테이블 삭제

• update_table - 테이블 구조 수정

📋 COLUMN 관리 (3개 도구):

• add_column - 데이터 유형이 있는 컬럼 추가

• delete_column - 컬럼 삭제

• update_column - 컬럼 속성 변경

🧮 MEASURE 관리 (3개 도구):

• create_measure - 계산된 측정값(DAX) 생성

• delete_measure - 측정값 삭제

• update_measure - DAX 식 업데이트

📈 REPORT 관리 (3개 도구):

• create_report - 새 보고서 생성

• delete_report - 보고서 삭제

• clone_report - 보고서 복제

📥 DATA 가져오기 (2개 도구):

• add_table_rows - 테이블에 데이터 추가

• clear_table_rows - 테이블 데이터 지우기

🌐 GATEWAY 관리 (2개 도구):

• get_gateways - gateway 목록 가져오기

• get_gateway_datasources - gateway 데이터 소스 가져오기

총 28개의 완전한 기능을 갖춘 PowerBI 완전 관리용 MCP 도구!

지원 기능:

• ✅ PowerBI 완전 관리: workspace 생성부터 시각화 추가까지

• ✅ Azure AD 인증 (Service Principal)

• ✅ 자동 토큰 갱신

• ✅ 포괄적인 오류 처리 및 로깅

• ✅ 모든 주요 엔티티에 대한 CRUD 작업

• ✅ DAX 쿼리 실행 및 계산된 측정값

• ✅ 데이터 가져오기 및 테이블 관리

• ✅ 외부 데이터 소스를 위한 Gateway 통합

• ✅ Workspace 및 권한 관리

📋 요구 사항

• Node.js 18+

• TypeScript

• Azure AD에 등록된 애플리케이션

• Power BI API 권한

🚀 설치

1. 저장소 복제 및 의존성 설치

git clone <repository-url>
cd powerbi_mcp_server
npm install

2. Azure AD 애플리케이션 설정

1. Azure Portal → App registrations로 이동

2. 새 애플리케이션을 만들거나 기존 애플리케이션 사용

3. "API permissions" 섹션에서 추가:

   • Power BI Service 권한:

     • Dataset.Read.All

     • Dataset.ReadWrite.All

     • Report.Read.All

     • Workspace.Read.All

   • Microsoft Graph (선택 사항):

     • User.Read

4. "Certificates & secrets" 섹션에서 새 client secret 생성

5. Application (client) ID, Directory (tenant) ID 및 client secret 복사

3. 환경 변수 설정

.env.example을 .env로 복사하고 작성:

cp .env.example .env

.env 편집:

# Azure AD Configuration
AZURE_CLIENT_ID=your_application_client_id
AZURE_CLIENT_SECRET=your_client_secret
AZURE_TENANT_ID=your_tenant_id

# PowerBI API Configuration  
POWERBI_API_URL=https://api.powerbi.com/v1.0/myorg

# Logging
LOG_LEVEL=info

4. 프로젝트 빌드

npm run build

🎮 사용법

서버 실행

npm start
# или для development:
npm run dev

Claude Desktop과 통합

Claude Desktop 구성 파일에 추가:

{
  "mcpServers": {
    "powerbi": {
      "command": "node",
      "args": ["/path/to/powerbi_mcp_server/build/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "your_client_id",
        "AZURE_CLIENT_SECRET": "your_client_secret", 
        "AZURE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

MCP 호환 클라이언트에서 사용

연결 후 다음 도구를 사용할 수 있습니다:

Workspaces 가져오기

get_workspaces()

Datasets 가져오기

get_datasets(workspace_id?: string)

DAX 쿼리 실행

query_dataset(
  dataset_id: "your-dataset-id",
  dax_query: "EVALUATE VALUES('Table'[Column])",
  workspace_id?: "workspace-id"
)

테이블이 있는 새 dataset 생성

create_dataset(
  name: "Sales Dataset",
  tables: [{
    name: "Sales",
    columns: [
      { name: "Date", dataType: "Datetime" },
      { name: "Amount", dataType: "Double" },
      { name: "Product", dataType: "String" }
    ],
    measures: [{
      name: "Total Sales",
      expression: "SUM(Sales[Amount])",
      formatString: "Currency"
    }]
  }],
  workspace_id?: "workspace-id"
)

테이블에 데이터 추가

add_table_rows(
  dataset_id: "dataset-id",
  table_name: "Sales",
  rows: [
    ["2024-01-01", 1000, "Product A"],
    ["2024-01-02", 1500, "Product B"]
  ],
  workspace_id?: "workspace-id"
)

📊 사용 예시

예시 1: 모든 workspace 가져오기

// Tool call: get_workspaces
// Response:
{
  "success": true,
  "data": [
    {
      "id": "workspace-guid",
      "name": "My Workspace", 
      "isReadOnly": false,
      "isOnDedicatedCapacity": true
    }
  ],
  "count": 1
}

예시 2: DAX 쿼리

// Tool call: query_dataset
{
  "dataset_id": "dataset-guid",
  "dax_query": "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)",
  "workspace_id": "workspace-guid"
}

// Response:
{
  "success": true,
  "data": {
    "tables": [
      {
        "rows": [
          ["Product A", 1000],
          ["Product B", 800]
        ]
      }
    ]
  }
}

🔧 개발

프로젝트 구조

src/
├── auth.ts          # Azure AD authentication
├── powerbi-client.ts # PowerBI REST API client  
├── server.ts        # MCP server implementation
├── types.ts         # TypeScript interfaces
├── logger.ts        # Logging configuration
└── index.ts         # Entry point

개발 명령어

npm run build    # Сборка TypeScript
npm run dev      # Development режим
npm start        # Production запуск

🛡️ 보안

• ✅ 안전한 토큰 저장 및 자동 갱신

• ✅ 자격 증명 또는 토큰은 절대 로그에 기록되지 않음

• ✅ 모든 수신 매개변수 검증

• ✅ 모든 API 호출에 HTTPS 사용

• ✅ 모든 시나리오에 대한 오류 처리

📝 로깅

서버는 Winston을 사용하여 로깅합니다. 로깅 수준은 LOG_LEVEL 변수를 통해 설정됩니다:

• error - 오류만

• warn - 경고 및 오류

• info - 정보 메시지 (기본값)

• debug - 상세 디버그 정보

❗ 문제 해결

문제: "Authentication failed"

해결 방법: Azure AD 자격 증명 및 권한의 정확성을 확인하세요

문제: "Dataset not found"

해결 방법: service principal이 workspace/dataset에 액세스할 수 있는지 확인하세요

문제: "DAX query failed"

해결 방법: DAX 쿼리 구문과 dataset에 대한 액세스 권한을 확인하세요

문제: "MCP connection failed"

해결 방법: 서버가 올바르게 실행되고 stdio를 통해 액세스 가능한지 확인하세요

📖 추가 리소스

• Model Context Protocol Specification

• Power BI REST API Documentation

• Azure AD Authentication Guide

• DAX Reference

📄 라이선스

ISC License

🤝 프로젝트 기여

Pull requests 및 issue reports를 환영합니다. 변경 전에:

1. 모든 테스트가 통과하는지 확인

2. 프로젝트의 code style 준수

3. 필요한 경우 문서 업데이트

Model Context Protocol ecosystem을 위해 제작됨 🚀