Power BI Local MCP Server (Python)

Servidor MCP que conecta ao motor Analysis Services Tabular local que o Power BI Desktop expõe enquanto está com um arquivo aberto. Funciona com .pbix e .pbip. 100% local: sem Azure AD, sem login online, sem publicar nada na nuvem.

Pré-requisitos

• Windows. O driver ADOMD.NET e a descoberta de porta são específicos de Windows.

• Python 3.10+ (python --version).

• .NET Runtime 8 — download. Não é o .NET Framework que já vem no Windows: o driver roda sobre o .NET moderno (CoreCLR). O Runtime basta; o SDK não é necessário.

• Power BI Desktop, com um arquivo aberto na hora do uso.

Você não precisa do SQL Server Management Studio. O driver ADOMD.NET é baixado direto do nuget.org (~2 MB) pelo driver_setup.py.

Related MCP server: mcp-powerbi-desktop

Instalar

Rode o instalar.bat (duplo clique), ou manualmente:

pip install -r requirements.txt
python driver_setup.py

O driver_setup.py baixa o pacote NuGet oficial Microsoft.AnalysisServices.AdomdClient.NetCore.retail.amd64 e extrai os DLLs para vendor/. Se a máquina já tiver o driver no cache do NuGet ou no GAC, ele reaproveita e não baixa nada.

Instalar como plugin do Claude Code

Este repositorio e um plugin do Claude Code e tambem um marketplace de um plugin so. Para instalar:

/plugin marketplace add djorshuam/claude-mcp-powerbi
/plugin install powerbi-local@powerbi-local-marketplace

Depois de instalar, rode /powerbi-setup uma vez: ele instala as dependencias Python, confere o runtime .NET e baixa o driver ADOMD.

Se voce tem varias versoes de Python, informe o caminho completo do python.exe na opcao Caminho do python.exe do plugin -- e o mesmo problema que o command do Claude Desktop resolve, so que pela config do plugin.

O plugin traz:

• o servidor MCP powerbi-local com as 5 ferramentas

• a skill powerbi-analysis, que ensina o fluxo correto (porta primeiro) e as armadilhas de DAX/DMV

• o comando /powerbi-setup para diagnostico

Configurar no Claude Desktop

No claude_desktop_config.json:

{
  "mcpServers": {
    "powerbi-local": {
      "command": "C:\\Python314\\python.exe",
      "args": ["C:\\CAMINHO\\PARA\\powerbi-mcp-python\\server.py"]
    }
  }
}

Use o caminho completo do python.exe, não só "python", se houver mais de uma versão instalada — o Claude Desktop pode resolver para uma que não tem as dependências.

Salve e reinicie o Claude Desktop completamente.

Ferramentas

Comece sempre por list_open_instances para obter a porta.

Testar manualmente

python server.py

O processo fica esperando input via stdio — é o comportamento normal de um servidor MCP, não um travamento. Ctrl+C para sair.

Notas de implementação

Coisas que custaram tempo para descobrir e que não são óbvias:

• pythonnet.load("coreclr") antes de import clr. No pythonnet 3.x o runtime .NET não é carregado sozinho, e sem isso o clr.AddReference falha em resolver os tipos do assembly.

• A pasta de workspace muda conforme a instalação do Power BI. Versão MSI usa %LOCALAPPDATA%\Microsoft\Power BI Desktop\; versão da Microsoft Store usa %USERPROFILE%\Microsoft\Power BI Desktop Store App\. O pbi_discovery.py varre as duas.

• msmdsrv.port.txt é UTF-16 little-endian sem BOM.

• Os DMVs aceitam só um subconjunto restrito de SQL. Não permitem WHERE sobre coluna booleana (WHERE [IsHidden] = FALSE falha com "Uma expressão Booliana não é permitida no contexto") nem INNER JOIN. Por isso o filtro de tabelas ocultas e o cruzamento medida→tabela são feitos em Python.

Limitações conhecidas

• Só enxerga instâncias do usuário Windows atual (lê %USERPROFILE%).

• run_dax_query trunca em 500 linhas.

• Somente leitura: não cria nem altera medidas.

• Requer acesso a nuget.org na primeira instalação. Em rede corporativa com proxy bloqueando, copie a pasta vendor/ de outra máquina.