# 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](https://dotnet.microsoft.com/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`.

## 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`:

```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

| Ferramenta | O que faz |
|---|---|
| `list_open_instances` | Descobre instâncias abertas do Power BI e suas portas |
| `list_databases` | Lista modelos disponíveis numa porta |
| `list_tables` | Lista tabelas visíveis do modelo |
| `list_measures` | Lista medidas com a expressão DAX completa |
| `run_dax_query` | Executa `EVALUATE ...` e retorna as linhas (máx. 500) |

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.