str-mcp-purview

MCP Server for Microsoft Purview Integration - with an optional D&D flavour.

This project implements a Model Context Protocol (MCP) server that integrates with Microsoft Purview, allowing LLMs to interact with Purview data through a secure interface. The server provides tools to monitor sensitivity label changes, analyze audit logs, manage data sources, and gain insights from your Microsoft Purview implementation.

Features

• 🔍 Audit Log Analysis: Access and analyze Purview audit logs to monitor data governance activities
• 🏷️ Sensitivity Label Tracking: Monitor changes to sensitivity labels in emails and documents
• 🔄 Data Source Scanning: Trigger scans of your data sources programmatically
• 📊 Data Catalog Insights: Get summary statistics about your entire data estate
• 🔗 Data Lineage Exploration: Visualize and analyze how data flows through your organization

Prerequisites

• Python 3.8 or higher
• An Azure subscription with Purview configured
• Appropriate permissions to access Purview resources
• UV package manager installed

Installation

1. Clone this repository:

   git clone <your-repo-url>
   cd str-mcp-purview

2. Configure your environment variables:

   cd src
   cp .env.template .env

   Then edit the .env file with your Purview account details and authentication information.

3. Run the server, and install dependencies: at the same time

   uv run server.py

Configuration

The server uses environment variables for configuration. Copy the .env.template file to .env and fill in:

# Azure Purview Configuration
PURVIEW_ACCOUNT_NAME=your-purview-account-name
PURVIEW_ENDPOINT=https://your-purview-account-name.purview.azure.com

# Azure Subscription Information
AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_RESOURCE_GROUP=your-resource-group-name

# Authentication (DefaultAzureCredential will be used if these are not provided)
# For service principal authentication
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Authentication

This server supports multiple authentication methods following Azure best practices:

1. Managed Identity: When deployed to Azure, uses system-assigned or user-assigned managed identities (recommended)
2. DefaultAzureCredential: Tries multiple authentication methods in sequence, including environment variables, managed identity, and interactive login
3. Service Principal: Falls back to client secret authentication if client ID, client secret, and tenant ID are provided

Starting the MCP Server

Start the server using one of these methods:

Basic Start

cd str-mcp-purview
python src/server.py

Using MCP CLI

# Standard mode
mcp run src/server.py

# Development mode with inspector
mcp dev src/server.py

Integration with Claude Desktop or Other MCP Clients

To install the server as an MCP extension:

mcp install src/server.py --name "Purview Insights"

Available Tools

The MCP server exposes these tools for LLMs:

get_audit_logs

Retrieve audit logs from Purview for a specified time period.

Parameters:

• start_time: Start time in ISO format (YYYY-MM-DDTHH:MM:SS)
• end_time: (Optional) End time in ISO format, defaults to current time
• limit: Maximum number of logs to return (default: 100)

Example usage:

logs = await get_audit_logs(start_time="2025-04-10T00:00:00", limit=50)

get_sensitivity_label_changes

Get a report of sensitivity label changes in a specified time period.

Parameters:

• start_time: Start time in ISO format (YYYY-MM-DDTHH:MM:SS)
• end_time: (Optional) End time in ISO format, defaults to current time

Example usage:

report = await get_sensitivity_label_changes(start_time="2025-04-01T00:00:00")

scan_data_source

Initiate a scan on a Purview data source.

Parameters:

• data_source_name: Name of the data source to scan
• scan_level: Type of scan (Incremental or Full)

Example usage:

result = await scan_data_source(data_source_name="MyDataLake", scan_level="Full")

get_data_catalog_summary

Get a summary of the data catalog including asset counts by type.

Example usage:

summary = await get_data_catalog_summary()

get_data_lineage

Get data lineage information for a specific entity.

Parameters:

• entity_id: ID of the entity to retrieve lineage for
• depth: Depth of lineage graph to retrieve (default: 3)

Example usage:

lineage = await get_data_lineage(entity_id="guid-123-456", depth=5)

Available Resources

The server provides these information resources:

purview-overview

Provides an overview of your Purview account configuration and status.

email-sensitivity-guide

Provides guidance on email sensitivity labels and their management.

Security Considerations

This server follows Azure best practices for security:

1. Secure Authentication: Uses DefaultAzureCredential for proper authentication chains
2. No Hardcoded Credentials: All sensitive information is stored in environment variables
3. Error Handling: Comprehensive error handling prevents information leakage
4. Least Privilege: Use RBAC in Azure to provide minimal required permissions to the service principal

Extending the Server

To add new tools:

1. Create a new function with the @mcp.tool() decorator
2. Define parameters and return types
3. Implement the tool functionality using the Purview client

To add new resources:

1. Create a new function with the @mcp.resource(path="your-path") decorator
2. Return the content as a string (Markdown format recommended)

Troubleshooting

If you encounter issues:

1. Authentication Errors: Verify your environment variables and check if the service principal has sufficient permissions
2. Connection Issues: Ensure your Purview endpoint is correctly specified
3. Tool Errors: Check the error logs for specific error messages

Solutions Referenced

• Microsoft Purview documentation
• Microsoft Purview Python SDK tutorial
• Azure Identity authentication library
• Microsoft Purview sensitivity labels
• Model Context Protocol (MCP) Python SDK

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.