Metadata-Version: 2.4
Name: powerbi-report-mcp
Version: 1.0.0
Summary: MCP server for editing Power BI PBIP report visualisations
Project-URL: Repository, https://github.com/mattbeard0/powerbi-report-mcp
Project-URL: Issues, https://github.com/mattbeard0/powerbi-report-mcp/issues
Author-email: Matt Beard <github@mattbeard.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,pbip,power-bi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: ==3.14.*
Requires-Dist: mcp[cli]==1.28.1
Requires-Dist: pydantic==2.13.4
Description-Content-Type: text/markdown

# powerbi-report-mcp

An [MCP](https://modelcontextprotocol.io) server for reading and editing the
**report/visual layer of Power BI PBIP projects** — pages, visuals, field
bindings, formatting, and themes — directly on disk, so AI assistants can
build and restyle reports alongside you.

It pairs with Microsoft's official
[powerbi-modeling-mcp](https://www.npmjs.com/package/@microsoft/powerbi-modeling-mcp)
(semantic model: tables, measures, relationships); this server deliberately
never touches the semantic model.

## Features

- **37 tools** covering connections, pages, visuals, field wells, format
  patching, themes, report settings, and style profiles.
- **Implicit active report** — `connection_name` is optional on every tool;
  the most recently opened/used report is the default target.
- **Git-style undo** — every edit is snapshotted per connection; `undo()`
  rolls back one step at a time (no redo), and `list_history()` shows the
  undo stack.
- **Atomic writes** — files are written via temp-file rename so Power BI
  Desktop never sees a half-written JSON file.
- **Schema-validated models** — Pydantic models mirror Microsoft's published
  PBIP JSON schemas, with a discriminated union per visual family.
- **Style profiles** — capture fonts, colours, borders, and canvas size in a
  reusable JSON profile and distil it into a report, page, or single visual
  with `apply_style`; only the parts relevant to the scope are applied.
- **Extension visual types** — register custom/AppSource visuals at runtime
  with the `register_visual_extension` tool; usable immediately, no restart.
- **stdio and HTTP transports** — spawned per client (stdio, default) or one
  instance serving many clients via `--transport http`, with each client in
  its own isolated session.

## Quick start

Requires [uv](https://docs.astral.sh/uv/) (Python 3.12+ is fetched
automatically). Two officially supported ways to run it:

**Usage — PyPI, stdio** (recommended for normal use):

```json
{
  "powerbi-report-mcp": {
    "type": "stdio",
    "command": "uvx",
    "args": ["powerbi-report-mcp"]
  }
}
```

**Development — local clone, HTTP** (for working on the server itself, with
live edits and no rebuild step). Run it yourself in a terminal, on a port you
pick:

```bash
git clone https://github.com/mattbeard0/powerbi-report-mcp.git
cd powerbi-report-mcp
uv run powerbi-report-mcp --transport http --port 8731
```

...then point your client at `http://127.0.0.1:8731/mcp` — a custom
connector for Claude Desktop, an `mcpServers` `"url"` entry for clients that
support it directly. This is also the route to remote-only clients like
ChatGPT, and to serving several clients from one process (each gets its own
isolated session — connections and undo history — touching the same report
only when each explicitly opens it).

Avoid running `uv run powerbi-report-mcp` as a **stdio** command on Windows —
the extra `uv.exe` process layer can stall the client's connect handshake
(confirmed with Claude Desktop and MCP Inspector); use HTTP instead.

Then in your assistant: *"Open C:/Projects/MyReport.Report and add a card
visual showing Total Sales."*

**[docs/installation.md](docs/installation.md) has copy-paste setup for
Claude Desktop, Claude Code, Codex / Codex CLI, ChatGPT, VS Code, and
Cursor** — each from PyPI or from a local folder — plus the Microsoft
modeling MCP.

## Development

```bash
uv sync                                  # includes the dev dependency group
uv run pytest                            # unit tests (network tests excluded)
uv run pytest -m network                 # live schema-conformance tests
uv run ruff check src tests
uv run mypy src
```

## License

[MIT](LICENSE)
