# Fabric Report MCP

[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![MCP Server](https://img.shields.io/badge/MCP%20Server-Compatible-green.svg)](https://github.com/anthropics/mcp)
[![DXT](https://img.shields.io/badge/DXT-Compatible-orange.svg)](https://github.com/anthropics/dxt)
[![PBIR](https://img.shields.io/badge/PBIR-Compatible-blue.svg)](https://learn.microsoft.com/en-us/power-bi/developer/projects/projects-report?tabs=desktop#definitionpbir)
[![License](https://img.shields.io/badge/license-Non--Commercial-red.svg)](LICENSE)

MCP server for managing Microsoft Fabric Reports with lifecycle management, filtering, and content manipulation.

**Important:** 
- Requires Azure AD authentication to access Microsoft Fabric workspaces.
- Requires PBIR format reports for most tools.


## Quick Start

### For Claude Desktop Users (Easiest)

**Prerequisites**: 
1. Python 3.8+ must be installed and in your PATH
   - **Mac/Linux**: Usually pre-installed as `python3`
   - **Windows**: Download from [python.org](https://python.org) - during installation, check "Add Python to PATH"

2. Install required Python packages:
   ```bash
   # For Mac/Linux:
   pip3 install fastmcp msal httpx pydantic python-dotenv
   
   # For Windows:
   pip install fastmcp msal httpx pydantic python-dotenv
   ```

**Installation**:
1. Download `fabric-report-mcp.dxt` from releases
2. Double-click to install in Claude Desktop
3. Configure Azure AD authentication (see Authentication section)

### For Other MCP Clients

1. Clone repository
2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Configure your MCP client to use this server. Example for VS Code:
```json
{
  "mcpServers": {
    "fabric-report-mcp": {
      "command": "python3",
      "args": ["path/to/fabric-report-mcp/src/server.py"]
    }
  }
}
```

4. Set up authentication using environment variables
5. Start using the server through your MCP client

6. For enhanced functionality, use with related MCP servers:
   - [Fabric Workspace Reader MCP](https://github.com/data-goblin/fabric-workspace-reader-mcp): Explore workspaces and discover resources
   - [Fabric Model Reader MCP](https://github.com/data-goblin/fabric-model-reader-mcp): Analyze semantic models and execute DAX queries

### Authentication

There are three options for authentication:

1. Azure CLI, which you can install and then login by using `az login`
2. Azure SDK
3. Configuration of a personal access token or Azure AD app registration



## Available Tools

### list_reports
List all reports in a Fabric workspace with optional result limiting.

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `max_results` (optional): Maximum number of reports to return

**Example usage:**
```
# List all reports in workspace
list_reports(workspace_id="12345678-1234-1234-1234-123456789012")

# Limit to first 10 reports
list_reports(workspace_id="12345678-1234-1234-1234-123456789012", max_results=10)
```

### get_report_content
Get report definition with advanced filtering and pagination support for large reports.

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `report_id` (required): The ID of the report
- `format` (optional, default: "PBIR"): Format of definition ("PBIR" or "PBIP")
- `include_pages` (optional): List of page names to include
- `exclude_pages` (optional): List of page names to exclude
- `include_visuals` (optional): List of visual IDs to include
- `exclude_visuals` (optional): List of visual IDs to exclude
- `max_definition_length` (optional): Maximum length for large definitions
- `offset` (optional, default: 0): Character offset for pagination

**Example usage:**
```
# Get complete report definition
get_report_content(workspace_id="...", report_id="...")

# Get only specific pages
get_report_content(workspace_id="...", report_id="...", include_pages=["Page1", "Dashboard"])

# Get paginated definition (first 50000 characters)
get_report_content(workspace_id="...", report_id="...", max_definition_length=50000, offset=0)

# Exclude certain pages
get_report_content(workspace_id="...", report_id="...", exclude_pages=["Hidden Page"])
```

### update_report_metadata
Update report metadata (display name and description only).

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `report_id` (required): The ID of the report
- `display_name` (optional): New display name for the report
- `description` (optional): New description for the report

**Example usage:**
```
# Update display name
update_report_metadata(workspace_id="...", report_id="...", display_name="New Report Name")

# Update description
update_report_metadata(workspace_id="...", report_id="...", description="Updated report description")

# Update both
update_report_metadata(workspace_id="...", report_id="...", display_name="New Name", description="New description")
```

### update_report_content
Update the complete report definition/content.

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `report_id` (required): The ID of the report
- `definition` (required): The complete report definition object

**Example usage:**
```
# First get the current definition, modify it, then update
current_def = get_report_content(workspace_id="...", report_id="...")
# ... modify definition ...
update_report_content(workspace_id="...", report_id="...", definition=modified_def)
```

### create_new_report
Create a new report or copy an existing one.

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `display_name` (required): Display name for the new report
- `description` (optional): Description for the new report
- `definition` (optional): Report definition (from get_report_content)

**Example usage:**
```
# Create empty report
create_new_report(workspace_id="...", display_name="New Report")

# Copy existing report
source_def = get_report_content(workspace_id="...", report_id="source-report-id")
create_new_report(workspace_id="...", display_name="Copy of Report", definition=source_def["definition"])
```

### delete_workspace_report
Delete a report from a workspace (requires confirmation).

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `report_id` (required): The ID of the report to delete
- `confirm` (required): Must be set to `true` to confirm deletion

**Example usage:**
```
# Delete report (requires explicit confirmation)
delete_workspace_report(workspace_id="...", report_id="...", confirm=true)
```

### download_theme_json
Extract theme configurations from published Power BI reports and save as standalone theme files.

**Parameters:**
- `workspace_id` (required): The ID of the workspace
- `report_id` (required): The ID of the report to extract theme from
- `output_path` (optional): Directory to save the theme file (defaults to current directory)
- `theme_name` (optional): Custom name for the theme file (defaults to report theme name)

### apply_theme_json
Apply theme configurations to local PBIP reports with proper schema compliance.

**Parameters:**
- `theme_source` (required): Path to theme.json file OR source report ID for copying
- `target_type` (required): Either "local" for local PBIP or "published" for Fabric reports
- `target_path` (optional): Path to local PBIP folder (required for local targets)
- `target_workspace_id` (optional): Target workspace ID (required for published targets)
- `target_report_id` (optional): Target report ID (required for published targets)
- `source_workspace_id` (optional): Source workspace ID (when copying from another report)
- `theme_name` (optional): Name for the applied theme (default: "CustomTheme")

**Note:** `download_theme_json` and `apply_theme_json` support both PBIR and PBIR-Legacy format reports.

## Architecture

The server follows a clean composition architecture:

```
src/
├── auth.py                     # Azure AD authentication
├── api_client.py              # Fabric API HTTP client  
├── tools/                     # Individual tool implementations
│   ├── list_reports.py
│   ├── get_report_definition.py
│   ├── update_report.py
│   ├── update_report_definition.py
│   ├── create_report.py
│   └── delete_report.py
└── server.py                  # MCP server composition
```

## Running the Server

### Direct Execution
```bash
python src/server.py
```

### Using Run Scripts
```bash
# Windows
run-server.bat

# Mac/Linux
./run-server.sh
```

## How to Contribute

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the existing patterns
4. Test your changes with sample reports
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## License

This project is licensed under a Non-Commercial License. See [LICENSE](LICENSE) for details.

## Troubleshooting

### Common Issues

**Authentication failures:**
- Verify Azure AD credentials are correctly configured
- Ensure the service principal has necessary Fabric permissions
- Check that the tenant ID, client ID, and client secret are valid

**Connection timeouts:**
- Verify network connectivity to Microsoft Fabric endpoints
- Check firewall settings if running behind corporate proxy
- Consider increasing timeout values for large reports

**Report definition errors:**
- Ensure PBIR format compatibility when using report definitions
- Validate JSON structure before sending updates
- Check that all required fields are present in report objects

## Security & Privacy Disclaimer

This software was created by me for me. I am sharing it for educational and personal use.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. THE USER ASSUMES ALL RESPONSIBILITY AND RISK FOR THE USE OF THIS SOFTWARE.

**DATA SECURITY AND PRIVACY**: This extension accesses Microsoft Fabric and Power BI data using your provided credentials. The author assumes NO responsibility for data security, privacy, or confidentiality. Users are SOLELY responsible for:
- Protecting their authentication credentials
- Ensuring compliance with their organization's data policies
- Managing access to sensitive or confidential data
- Any data breaches or unauthorized access resulting from use of this extension

By using this code, you acknowledge that you are fully responsible for all data security and privacy implications.

## AI Disclaimer

The code and docs in this repo were generated with the help of Claude Sonnet 4, Claude Opus 4, and Gemini 2.5 Pro using various agentic coding tools.