Metadata-Version: 2.4
Name: powerbi-vis-mcp
Version: 2.0.0
Summary: MCP server for editing Power BI PBIP report visualisations
Project-URL: Repository, https://github.com/mattbeard0/powerbi-visualising-mcp
Project-URL: Issues, https://github.com/mattbeard0/powerbi-visualising-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.15,>=3.12
Requires-Dist: mcp[cli]==1.28.1
Requires-Dist: pydantic==2.13.4
Description-Content-Type: text/markdown

# powerbi-vis-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

- **34 tools** covering connections, pages, visuals, field wells, format
  patching, themes, and report settings.
- **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.
- **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 ways to run it — everything else is client wiring:

```bash
uvx powerbi-vis-mcp        # from PyPI — no clone, no install, like npx
uv run powerbi-vis-mcp     # from a clone — one command inside the folder
```

Register whichever you prefer with your MCP client (stdio):

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

Or start one HTTP instance and point every client at it — each client
gets its own isolated session (connections and undo history); clients
touch the same report only when each explicitly opens it. This is also
the route to remote-only clients like ChatGPT:

```bash
uvx powerbi-vis-mcp --transport http     # serves http://127.0.0.1:8000/mcp
```

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)
