Copilot Powerbi Desktop MCP Bridge

🔗 副驾驶+Power BI桌面MCP桥

用于在Microsoft Copilot Studio中利用Power BI桌面的数据模型的HTTP Bridge服务。

 ](https://nodejs.org/) 

______________________________________________________________________

📋 目录

• 概要
• 架构
• 快速开始（5分钟）
• 详细安装指南
• 设置
• API参考
• MCP工具列表
• 设置Power Platform连接
• 使用方法
• 故障排除
• 开发者指南
• 许可证

______________________________________________________________________

🎯 概要

这个项目 Copilot工作室在本地PC上 Power BI 桌面版 充当Bridge，允许您直接访问数据模型。

解决的问题

• ❌ 传统方式：Copilot Studio只能连接云服务
• Power BI桌面的本地型号不能直接从Copilot访问
• ✅ 此解决方案：通过HTTP Bridge连接本地模型和云Copilot

主要功能

• 🔌 MCP协议支持：通过Model Context Protocol进行标准化通信
• 🌐 HTTP REST API：与Copilot Studio Custom Connector兼容的REST端点
• 🔒 安全设计：绑定localhost，验证可选API密钥
• 🚀 易于安装：一个可执行文件即可立即执行
• 📊 Power BI数据访问：执行表、列、DAX查询、关系查询等
• 🔍 MCP自动导航：自动扫描MCP可执行文件，如VS Code Extension文件夹
• 📥 MCP自动下载：从VS Code Marketplace自动下载MCP服务器
• 🔗 Power BI自动连接：自动检测和连接本地Power BI桌面实例
• 🔧 交互设置：通过设置向导简化初始配置

使用案例

1. 自然语言查询：“上个月的销售额是多少？”→自动生成和运行DAX查询
2. 浏览数据：“此模型中有哪些表？”→查询元数据
3. 自动化报告：Copilot基于Power BI数据创建洞察

______________________________________________________________________

🏗️ 架构

┌─────────────────────┐
│  Copilot Studio     │  ← 클라우드
└──────────┬──────────┘
           │ HTTPS
           ▼
┌─────────────────────┐
│  On-premises        │  ← Gateway
│  Data Gateway       │
└──────────┬──────────┘
           │ HTTP
           ▼
┌─────────────────────┐
│  HTTP Bridge        │  ← 이 프로젝트 (localhost:5050)
│  (Node.js)          │
│  ┌───────────────┐  │
│  │ REST API      │  │  ← /mcp/tools/list, /mcp/tools/call
│  │ JSON-RPC API  │  │  ← POST /mcp
│  │ Auto-Connect  │  │  ← Power BI 자동 연결
│  └───────────────┘  │
└──────────┬──────────┘
           │ stdio (MCP)
           ▼
┌─────────────────────┐
│ powerbi-modeling    │  ← MCP 서버 (자동 탐색/다운로드)
│ -mcp.exe            │
└──────────┬──────────┘
           │ COM/API
           ▼
┌─────────────────────┐
│  Power BI Desktop   │  ← 로컬
└─────────────────────┘

通信流

1. Copilot工作室 →请求网关（HTTPS）
2. 网关 →转发到Bridge（HTTP，本地网络）
3. 桥 →与MCP进程进行stdio通信（包括自动连接）
4. 主控程序 →与Power BI桌面交互（COM）
5. 响应按逆序传递

______________________________________________________________________

-快速入门（5分钟）

方法1:下载可执行文件（推荐-非开发者）

1. 确认前提条件

- Windows 10/11 - 安装和运行Power BI桌面（下载)

1. 下载Bridge

- Releases页面最新 pbi-mcp-bridge-win-x64-vX.X.X.zip 下载 - 解压缩（例如： C:\pbi-mcp-bridge\)

1. 执行

   # PowerShell에서 실행
   cd C:\pbi-mcp-bridge
   .\scripts\start.ps1

> 💡 powerbi-modeling-mcp.exe如果没有，将自动浏览VS Code Extension文件夹或运行交互式设置向导。

1. 确认

- 在浏览器中http://localhost:5050/health连接 - "status": "ok" 确认消息

方法2:PowerShell一键安装

# PowerShell을 관리자로 실행한 후
irm https://raw.githubusercontent.com/asomi7007/copilot-powerbi-desktop-mcp-bridge/master/scripts/install.ps1 | iex

方法3:从源位置安装（开发者）

# Node.js 20 이상 필요
git clone https://github.com/asomi7007/copilot-powerbi-desktop-mcp-bridge.git
cd copilot-powerbi-desktop-mcp-bridge
npm install
npm run build
npm start

______________________________________________________________________

📖 详细安装指南

前提条件

必需软件

💡 powerbi-modeling-mcp.exeBridge将自动导航或下载。无需单独安装。

可选

自动浏览MCP可执行文件

Bridge在启动时 powerbi-modeling-mcp.exe按以下顺序自动导航：

1. config.yaml指定给的绝对路径
2. VS Code Extensions文件夹（%USERPROFILE%\.vscode\extensions\analysis-services.powerbi-modeling-mcp-*)
3. VS Code Insiders Extensions文件夹
4. 文件夹/当前工作目录，如Bridge
5. %LOCALAPPDATA%, %PROGRAMFILES% 等一般安装路径
6. PATH环境变量

如果未找到：

• TTY环境：运行交互式设置向导（自动下载/输入路径/VS Code指南）
• 非TTY环境：尝试从VS Code Marketplace自动下载

安装步骤

步骤1:安装Bridge

选项A：可执行文件（推荐）

1. 发布从下载zip
2. 解压缩到所需位置（例如： C:\pbi-mcp-bridge\)
3. 准备配置文件（可选）：

   copy config.example.yaml config.yaml

选项B：安装源

git clone https://github.com/asomi7007/copilot-powerbi-desktop-mcp-bridge.git
cd copilot-powerbi-desktop-mcp-bridge
npm install
npm run build

步骤2：启动服务

# 수동 실행
.\scripts\start.ps1

# 인터랙티브 설정 마법사 실행
node dist/index.js --setup

# 또는 Windows 시작 시 자동 실행 (관리자 권한 필요)
.\scripts\register-startup.ps1

步骤3:检查动作

# 상태 확인
curl http://localhost:5050/health

# 또는 브라우저에서 http://localhost:5050/health 접속

正常响应示例：

{
  "status": "ok",
  "bridge": {
    "version": "1.0.0",
    "uptime": 120
  },
  "mcp": {
    "state": "running",
    "pid": 12345,
    "command": "C:\\Users\\...\\powerbi-modeling-mcp.exe"
  },
  "powerbi": {
    "connected": true
  }
}

ℹ️ status是 "ok" （正常，200）， "degraded" （MCP未执行，503） "error" （错误，500）之一。

______________________________________________________________________

设置⚙ENT

config.yaml

控制Bridge行为的主设置文件。

# HTTP 서버 설정
server:
  port: 5050              # 포트 번호 (기본: 5050)
  host: "127.0.0.1"       # 바인딩 주소 (보안상 localhost 권장)

# MCP 서버 설정
mcp:
  command: "powerbi-modeling-mcp.exe"  # MCP 실행 파일 경로 (자동 탐색 가능)
  args: []                              # 추가 명령줄 인수
  # cwd: "C:\\path\\to\\mcp"           # 작업 디렉토리 (선택)
  startupTimeoutMs: 10000               # 시작 타임아웃 (밀리초)
  requestTimeoutMs: 30000               # 요청 타임아웃 (밀리초)

# 보안 설정
security:
  # apiKey: "your-secret-key"          # API Key 인증 (주석 해제하여 활성화)
  corsOrigins:
    - "*"                               # CORS 허용 도메인

# 로깅 설정
logging:
  level: "info"                         # debug, info, warn, error
  # file: "logs/bridge.log"            # 로그 파일 경로 (선택)

环境变量（.env）

简单的设置也可以作为环境变量。 config.yaml优先级更高。

# Bridge 서버 설정
BRIDGE_PORT=5050
BRIDGE_HOST=127.0.0.1

# MCP 설정
MCP_COMMAND=powerbi-modeling-mcp.exe
# MCP_CWD=C:\path\to\mcp

# 보안
# API_KEY=your-secret-key-here

# 로깅
LOG_LEVEL=info
# LOG_FILE=logs/bridge.log

CLI参数

参数说明示例 |------|------|------| | --setup, --reconfigure 运行交互式设置向导| node dist/index.js --setup | | --reset-config |将config.yaml重置为默认值| node dist/index.js --reset-config | | --port |指定服务器端口| --port 8080 | | --host |指定绑定地址| --host 0.0.0.0 | | --mcp-command | MCP可执行文件路径| --mcp-command "C:\mcp\mcp.exe" | | --mcp-cwd | MCP工作目录| --mcp-cwd "C:\mcp" | | --api-key | API Key设置| --api-key "my-key" | | --log-level |日志级别| --log-level debug |

设置优先级

CLI 인수 > 환경변수 (.env) > config.yaml > 기본값

主要设置项目说明

______________________________________________________________________

📡 API参考

端点摘要

关于GET/-Bridge

curl http://localhost:5050/

回复：

{
  "name": "Copilot + Power BI Desktop MCP Bridge",
  "version": "1.0.0",
  "endpoints": {
    "mcp": "POST /mcp - Send JSON-RPC requests to MCP process",
    "mcpTools": "POST /mcp/tools/list, POST /mcp/tools/call - REST API for MCP tools",
    "health": "GET /health - Check bridge and MCP process status"
  }
}

GET/health-检查状态

curl http://localhost:5050/health

回复：

{
  "status": "ok",
  "bridge": {
    "version": "1.0.0",
    "uptime": 3600
  },
  "mcp": {
    "state": "running",
    "pid": 12345,
    "command": "powerbi-modeling-mcp.exe"
  },
  "powerbi": {
    "connected": true
  }
}

POST/mcp/tools/list-工具列表（REST）

Copilot Studio Custom Connector使用的REST端点。

curl -X POST http://localhost:5050/mcp/tools/list

回复：

{
  "tools": [
    {
      "name": "table_operations",
      "description": "Perform operations on semantic model tables...",
      "inputSchema": { "..." : "..." }
    },
    {
      "name": "dax_query_operations",
      "description": "Execute DAX queries...",
      "inputSchema": { "..." : "..." }
    }
  ]
}

POST/mcp/tools/call-运行工具（REST，自动连接）

Copilot Studio Custom Connector使用的关键端点。

💡 自动连接：如果Power BI桌面正在运行，将自动检测并连接本地实例。单独的 connection_operations 无需呼叫。

请求类型：

{
  "toolName": "도구이름",
  "toolArguments": "JSON 문자열 또는 객체"
}

示例1:查看表格列表

curl -X POST http://localhost:5050/mcp/tools/call ^
  -H "Content-Type: application/json" ^
  -d "{\"toolName\":\"table_operations\",\"toolArguments\":\"{\\\"request\\\":{\\\"operation\\\":\\\"List\\\"}}\"}"

示例2:运行DAX查询

curl -X POST http://localhost:5050/mcp/tools/call ^
  -H "Content-Type: application/json" ^
  -d "{\"toolName\":\"dax_query_operations\",\"toolArguments\":\"{\\\"request\\\":{\\\"operation\\\":\\\"Execute\\\",\\\"query\\\":\\\"EVALUATE ROW(\\\\\\\"Total Sales\\\\\\\", SUM(Sales[Amount]))\\\"}}\"}"

示例3:跳过toolArguments（使用默认值）

curl -X POST http://localhost:5050/mcp/tools/call ^
  -H "Content-Type: application/json" ^
  -d "{\"toolName\":\"table_operations\"}"

如果省略toolArguments，将应用特定于工具的默认值（例如： table_operations → { request: { operation: "List" } }).

toolArguments支持格式：

• JSON字符串： '{"request":{"operation":"List"}}'
• 双重编码的JSON: '"{\\"request\\":{\\"operation\\":\\"List\\"}}"'
• 对象： { "request": { "operation": "List" } }
• null/undefined/空字符串：使用工具特定的默认值

POST/mcp-JON-RPC转发（通用）

直接传递MCP JSON-RPC 2.0消息。

curl -X POST http://localhost:5050/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"tools/list\",\"params\":{}}"

回复：

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [ ]
  }
}

______________________________________________________________________

🛠️ MCP工具列表

可通过Bridge使用的MCP工具。所有工具都是嵌套的 request 使用对象结构。

工具使用示例

表格列表：

{ "toolName": "table_operations", "toolArguments": "{\"request\":{\"operation\":\"List\"}}" }

运行DAX查询：

{ "toolName": "dax_query_operations", "toolArguments": "{\"request\":{\"operation\":\"Execute\",\"query\":\"EVALUATE INFO.TABLES()\"}}" }

查询特定表格中的列：

{ "toolName": "column_operations", "toolArguments": "{\"request\":{\"operation\":\"List\",\"tableName\":\"Sales\"}}" }

测量列表：

{ "toolName": "measure_operations", "toolArguments": "{\"request\":{\"operation\":\"List\",\"tableName\":\"Sales\"}}" }

验证连接状态：

{ "toolName": "connection_operations", "toolArguments": "{\"request\":{\"operation\":\"Status\"}}" }

______________________________________________________________________

🔌 设置Power Platform连接

要在Copilot Studio中使用Bridge，请执行以下步骤：

步骤1：安装On-premises Data Gateway

1. 下载和安装Gateway

- 本地数据网关 下载 - 安装后登录Microsoft帐户

1. 配置网关

- 指定网关名称（例如“MyPC-Gateway”） - 设置和备份恢复密钥

1. 检查网关状态

- 在Power Platform管理中心查看网关列表 - 确认状态为“在线”

步骤2:创建Custom Connector

1. 连接Power Platform管理中心

- https://make.powerapps.com移动 - 选择环境

1. 创建Custom Connector

- 左菜单： 数据 → 自定义连接器 - +新的自定义连接器 → 从OpenAPI文件导入

1. 上传Swagger文件

- 此项目的 connector/apiDefinition.swagger.json 上载文件 - 连接器名称：“Power BI MCP Bridge”

1. 主机设置

- 一般 在选项卡中： - 主机： localhost:5050 →通过网关访问，保留localhost - 保安 选项卡： - 身份验证类型：“API密钥”（在Bridge中 apiKey） - 或“无身份验证”（首选项）

1. 创建连接器

- 右上 创建连接器 点击

步骤3:创建连接

1. 添加连接

- 数据 → 连接 → +新建连接 - 选择刚刚创建的“Power BI MCP Bridge”

1. 选择网关

- 检查“使用本地数据网关” - 选择在步骤1中安装的网关

1. 测试连接

- 创建连接后单击“测试”按钮 - 运行Health Check操作以确认成功

步骤4：在Copilot Studio中添加工具

1. 连接Copilot Studio

- https://copilotstudio.microsoft.com - 选择聊天机器人或新建聊天机器人

1. 添加工具

- 左菜单： 工作 → 连接器 - 添加“Power BI MCP Bridge”连接器

1. 配置任务

- ListTools 检查可用于操作的工具 - CallTool 使用任务运行工具：

     {
       "toolName": "table_operations",
       "toolArguments": "{\"request\":{\"operation\":\"List\"}}"
     }

1. 测试

- 在Copilot测试窗口中提问： - “给我看看桌子列表” - “告诉我销售表上的信息”

______________________________________________________________________

📖 使用方法

直接调用REST API（推荐）

1.确认状态

curl http://localhost:5050/health

2.查看可用工具列表

curl -X POST http://localhost:5050/mcp/tools/list

3.运行工具（DAX查询示例）

curl -X POST http://localhost:5050/mcp/tools/call ^
  -H "Content-Type: application/json" ^
  -d "{\"toolName\":\"dax_query_operations\",\"toolArguments\":\"{\\\"request\\\":{\\\"operation\\\":\\\"Execute\\\",\\\"query\\\":\\\"EVALUATE ROW(\\\\\\\"Total Sales\\\\\\\", SUM(Sales[Amount]))\\\"}}\"}"

JSON-RPC直接调用

curl -X POST http://localhost:5050/mcp ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"tools/call\",\"params\":{\"name\":\"table_operations\",\"arguments\":{\"request\":{\"operation\":\"List\"}}}}"

在Copilot Studio中使用

在Copilot Studio的Topics中使用Custom Connector操作：

1. 触发设置：识别用户问题
2. 运行任务: CallTool 调用（toolName+toolArguments）
3. 响应处理：将结果转换为自然语言进行回答

示例流程：

사용자: "매출 테이블에 어떤 컬럼이 있어?"
  ↓
Copilot: CallTool("column_operations", '{"request":{"operation":"List","tableName":"Sales"}}')
  ↓
Bridge → 자동 연결 → MCP → Power BI Desktop
  ↓
응답: { "content": [{ "type": "text", "text": "..." }] }
  ↓
Copilot: "매출 테이블에는 Date, Amount, Customer 등의 컬럼이 있습니다."

______________________________________________________________________

🔧 故障排除

MCP进程未启动

症状：

{
  "status": "degraded",
  "mcp": { "state": "stopped" }
}

解决方法：

1. 确认自动导航 -如果Bridge无法自动找到MCP exe：

   # 설정 마법사 실행
   node dist/index.js --setup

1. 检查VS Code Extension

   # VS Code에서 설치 확인
   dir "$env:USERPROFILE\.vscode\extensions\analysis-services.powerbi-modeling-mcp-*"

1. 手动布线

   # config.yaml
   mcp:
     command: "C:\\Users\\사용자\\.vscode\\extensions\\analysis-services.powerbi-modeling-mcp-xxx\\server\\powerbi-modeling-mcp.exe"

1. 检查日志

   # Bridge 로그 확인 (logging.file 설정한 경우)
   Get-Content logs\bridge.log -Tail 50

Power BI桌面连接失败

症状： MCP运行，但无法访问Power BI数据

解决方法：

1. 验证Power BI桌面的运行

   Get-Process -Name "PBIDesktop" -ErrorAction SilentlyContinue

1. 在Power BI桌面中打开文件

- 不是空的状态 .pbix 必须打开文件

1. 确认允许外部工具连接

- Power BI桌面选项→安全性→检查“允许连接外部工具”

1. 手动连接测试

   curl -X POST http://localhost:5050/mcp/tools/call ^
     -H "Content-Type: application/json" ^
     -d "{\"toolName\":\"connection_operations\",\"toolArguments\":\"{\\\"request\\\":{\\\"operation\\\":\\\"ListLocalInstances\\\"}}\"}"

网关连接失败

症状： Copilot Studio出现“网关不可用”错误

解决方法：

1. 检查网关状态

- 验证Windows服务是否正在运行“On-premises数据网关服务” - 在Power Platform管理中心检查网关状态“联机”

1. 防火墙设置

- 添加Bridge端口（默认5050）入站规则

   New-NetFirewallRule -DisplayName "PBI MCP Bridge" -Direction Inbound -LocalPort 5050 -Protocol TCP -Action Allow

1. 绑定网络

- config.yaml的 server.host被 0.0.0.0更改为以接收所有网络接口 - 安全注意：必须设置防火墙

API Key身份验证错误

症状： 401 Unauthorized

解决方法：

1. 验证API密钥

   # config.yaml
   security:
     apiKey: "your-key-here"

1. 添加标题

   curl -H "X-API-Key: your-key-here" http://localhost:5050/health

1. Custom Connector设置

- 在安全选项卡中选择“API密钥”身份验证类型 - 连接时输入API Key

______________________________________________________________________

👨‍💻 开发者指南

项目结构

copilot-powerbi-desktop-mcp-bridge/
├── src/
│   ├── index.ts                 # 엔트리포인트, CLI 인수 처리
│   ├── server.ts                # Express 서버 설정
│   ├── config.ts                # 설정 로더 (yaml + env + CLI)
│   ├── logger.ts                # Winston 로거
│   ├── mcp-client.ts            # MCP stdio 클라이언트
│   ├── mcp-discovery.ts         # MCP 실행파일 자동 탐색/다운로드
│   ├── interactive-setup.ts     # 인터랙티브 설정 마법사
│   ├── types.ts                 # TypeScript 타입 정의
│   ├── middleware/              # Express 미들웨어
│   │   ├── auth.ts              # API Key 인증
│   │   ├── request-logger.ts    # 요청 로깅
│   │   └── error-handler.ts     # 에러 핸들러
│   └── routes/                  # API 라우트
│       ├── mcp.ts               # POST /mcp (JSON-RPC)
│       ├── mcp-rest.ts          # POST /mcp/tools/list, /mcp/tools/call (REST)
│       └── health.ts            # GET /health
├── scripts/                     # PowerShell 스크립트
│   ├── install.ps1              # 설치 스크립트
│   ├── start.ps1                # 시작 스크립트
│   ├── stop.ps1                 # 중지 스크립트
│   ├── setup.ps1                # 설정 관리 스크립트
│   └── register-startup.ps1     # 시작프로그램 등록
├── connector/                   # Power Platform Custom Connector
│   ├── apiDefinition.swagger.json  # Swagger API 정의
│   └── apiProperties.json          # 커넥터 속성
├── .github/workflows/           # GitHub Actions CI/CD
│   └── build.yml                # 빌드 및 릴리스
├── plans/                       # 설계 문서
│   ├── ARCHITECTURE.md          # 아키텍처 설계 문서
│   └── COPILOT_STUDIO_COMPAT.md # Copilot Studio 호환 문서
├── tools_list.json              # MCP 도구 목록 참조
├── config.example.yaml          # 설정 예시
├── .env.example                 # 환경변수 예시
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md                    # 이 문서

构建

# TypeScript 컴파일
npm run build

# 개발 모드 (ts-node)
npm run dev

# 단일 .exe 빌드 (Windows)
npm run pkg:build

# 클린 빌드
npm run clean && npm run build

本地开发

# 의존성 설치
npm install

# 개발 서버 실행 (ts-node)
npm run dev

# 또는 빌드 후 실행
npm run build
npm start

脚本列表

代码样式

• TypeScript strict模式
• ESLint+Prettier（即将设置）
• 变量/函数名：camelCase
• 文件名：kebab-case

______________________________________________________________________

🤝 贡献

欢迎您的贡献！提交Pull Request之前：

1. 创建Fork和分支
2. 更改代码
3. 验证构建和测试
4. PR创建with详细说明

报告问题

错误报告或功能建议 问题请在注册。

______________________________________________________________________

📄 许可证

这个项目 MIT许可证 以下分发。

______________________________________________________________________

🙏 感谢的文章

本项目参考了以下开源项目：

• 模型上下文协议（MCP）
• powerbi建模mcp
• Express.js、Winston、TypeScript社区

______________________________________________________________________

📞 询问

• 开发商：Dream I系统
• 问题跟踪者:
• 文档: 平面图/建筑.md

______________________________________________________________________

制作❤️ Power BI和Copilot社区