Metadata-Version: 2.4
Name: powerbi-vis-mcp
Version: 0.1.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 :: 4 - Beta
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.12
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pydantic>=2.7
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

- **32 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).
- **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 by dropping
  JSON files into `~/.powerbi-vis-mcp/extensions/`.

## Quick start

Requires [uv](https://docs.astral.sh/uv/) (Python 3.12+ is fetched
automatically). No clone, no install — one command, exactly like `npx`.
Register it with your MCP client (e.g. `.mcp.json`):

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

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

Other sources, same single command:

```bash
uvx powerbi-vis-mcp@0.1.0                                # pin a release
uvx --from git+https://github.com/mattbeard0/powerbi-visualising-mcp.git powerbi-vis-mcp   # unreleased main
uvx --from <path-to-checkout> powerbi-vis-mcp            # local build
```

Developing the server itself? Use the editable run so local edits are live
(uvx caches builds by version):

```json
{
  "powerbi-vis-mcp": {
    "type": "stdio",
    "command": "uv",
    "args": ["run", "--project", "<path-to-repo>", "powerbi-vis-mcp"]
  }
}
```

See [docs/installation.md](docs/installation.md) for full setup, including
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)
