ms-fabric-mcp-server

A Model Context Protocol (MCP) server for Microsoft Fabric. Exposes Fabric operations (workspaces, notebooks, SQL, Livy, pipelines, jobs) as MCP tools that AI agents can invoke.

⚠️ Warning: This package is intended for development environments only and should not be used in production. It includes tools that can perform destructive operations (e.g., delete_item, delete_lakehouse_file, delete_activity_from_pipeline) and execute arbitrary code via Livy Spark sessions. Always review AI-generated tool calls before execution.

Quick Start

The fastest way to use this MCP server is with uvx:

uvx ms-fabric-mcp-server

Installation

# Using uv (recommended)
uv pip install ms-fabric-mcp-server

# Using pip
pip install ms-fabric-mcp-server

# With SQL support (requires pyodbc)
pip install ms-fabric-mcp-server[sql]

# With OpenTelemetry tracing
pip install ms-fabric-mcp-server[sql,telemetry]

Authentication

Uses DefaultAzureCredential from azure-identity - no explicit credential configuration needed. This automatically tries multiple authentication methods:

1. Environment credentials (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)
2. Managed Identity (when running on Azure)
3. Azure CLI credentials (az login)
4. VS Code credentials
5. Azure PowerShell credentials

No Fabric-specific auth environment variables are needed - it just works if you're authenticated via any of the above methods.

Usage

VS Code Integration

Add to your VS Code MCP settings (.vscode/mcp.json or User settings):

{
  "servers": {
    "MS Fabric MCP Server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ms-fabric-mcp-server"]
    }
  }
}

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fabric": {
      "command": "uvx",
      "args": ["ms-fabric-mcp-server"]
    }
  }
}

Codex Integration

Add to your Codex config.toml:

[mcp_servers.ms_fabric_mcp]
command = "uvx"
args = ["ms-fabric-mcp-server"]

Running Standalone

# Using uvx (no installation needed)
uvx ms-fabric-mcp-server

# Direct execution (if installed)
ms-fabric-mcp-server

# Via Python module
python -m ms_fabric_mcp_server

# With MCP Inspector (development)
npx @modelcontextprotocol/inspector uvx ms-fabric-mcp-server

Logging & Debugging (optional)

MCP stdio servers must keep protocol traffic on stdout, so redirect stderr to capture logs. Giving the agent read access to the log file is a powerful way to debug failures. You can also set AZURE_LOG_LEVEL (Azure SDK) and MCP_LOG_LEVEL (server) to control verbosity.

VS Code (Bash):

{
  "servers": {
    "MS Fabric MCP Server": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-lc",
        "LOG_DIR=\"$HOME/mcp_logs\"; LOG_FILE=\"$LOG_DIR/ms-fabric-mcp-$(date +%Y%m%d_%H%M%S).log\"; uvx ms-fabric-mcp-server 2> \"$LOG_FILE\""
      ],
      "env": {
        "AZURE_LOG_LEVEL": "info",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

VS Code (PowerShell):

{
  "servers": {
    "MS Fabric MCP Server": {
      "type": "stdio",
      "command": "powershell",
      "args": [
        "-NoProfile",
        "-Command",
        "$logDir=\"$env:USERPROFILE\\mcp_logs\"; New-Item -ItemType Directory -Force -Path $logDir | Out-Null; $ts=Get-Date -Format yyyyMMdd_HHmmss; $logFile=\"$logDir\\ms-fabric-mcp-$ts.log\"; uvx ms-fabric-mcp-server 2> $logFile"
      ],
      "env": {
        "AZURE_LOG_LEVEL": "info",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Programmatic Usage (Library Mode)

from fastmcp import FastMCP
from ms_fabric_mcp_server import register_fabric_tools

# Create your own server
mcp = FastMCP("my-custom-server")

# Register all Fabric tools
register_fabric_tools(mcp)

# Add your own customizations...

mcp.run()

Configuration

Environment variables (all optional with sensible defaults):

Copy .env.example to .env and customize as needed.

Available Tools

The server provides 57 core tools, with 3 additional SQL tools when installed with [sql] extras (60 total).

SQL Tools (Optional)

SQL tools require pyodbc and the Microsoft ODBC Driver for SQL Server (Driver 18 or 17 — the service auto-detects which is installed and prefers Driver 18; set FABRIC_ODBC_DRIVER to override):

# Install with SQL support
pip install ms-fabric-mcp-server[sql]

# On Ubuntu/Debian, install the ODBC driver first:
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18  # or msodbcsql17

If pyodbc is not available, the server starts with 57 tools (SQL tools disabled).

Development

# Clone and install with dev dependencies
git clone https://github.com/your-org/ms-fabric-mcp-server.git
cd ms-fabric-mcp-server
pip install -e ".[dev,sql,telemetry]"

# Run tests
pytest

# Run with coverage
pytest --cov

# Format code
black src tests
isort src tests

# Type checking
mypy src

Integration tests

Integration tests run against live Fabric resources and are opt-in. They require a pre-provisioned Fabric workspace, Lakehouse, Warehouse, and (for Copy Activity tests) at least one external-source connection. See Setup prerequisites below before your first run.

To get started locally, copy the example env file:

cp .env.integration.example .env.integration

Then fill in values matching your provisioned resources. The full set of variables (with inline comments grouping by purpose) lives in .env.integration.example; this list is for orientation:

Required for all integration tests:

• FABRIC_INTEGRATION_TESTS=1
• FABRIC_TEST_WORKSPACE_NAME — display name of the test workspace
• FABRIC_TEST_LAKEHOUSE_NAME — Lakehouse item in the workspace (used as the destination for Copy Activities)
• FABRIC_TEST_LAKEHOUSE_SQL_DATABASE — the Lakehouse's SQL endpoint database name (typically same as the Lakehouse name)
• FABRIC_TEST_WAREHOUSE_NAME — Warehouse item in the workspace (used by SQL DML tests)

Required for Copy Activity tests (Pipeline Flow):

• FABRIC_TEST_DEST_CONNECTION_ID — Fabric connection ID for the destination Lakehouse (used by all Copy Activity tests)

Per-engine source inputs — set all 5 vars of a block to enable that block's Copy Activity test; the test skips with a logged reason if any value is missing.

PostgreSQL source (e.g., VM-hosted Postgres reachable via a gateway):

• FABRIC_TEST_POSTGRES_CONNECTION_ID
• FABRIC_TEST_POSTGRES_SOURCE_TYPE (default PostgreSqlSource)
• FABRIC_TEST_POSTGRES_SCHEMA
• FABRIC_TEST_POSTGRES_TABLE
• FABRIC_TEST_POSTGRES_DEST_TABLE_NAME

SQL Server source (e.g., VM-hosted SQL Server, Azure SQL DB):

• FABRIC_TEST_SQLSERVER_CONNECTION_ID
• FABRIC_TEST_SQLSERVER_SOURCE_TYPE (default SqlServerSource)
• FABRIC_TEST_SQLSERVER_SCHEMA
• FABRIC_TEST_SQLSERVER_TABLE
• FABRIC_TEST_SQLSERVER_DEST_TABLE_NAME

Optional inputs (other flows skip cleanly when absent):

• Semantic Model: FABRIC_TEST_SEMANTIC_MODEL_TABLE, FABRIC_TEST_SEMANTIC_MODEL_COLUMNS, FABRIC_TEST_SEMANTIC_MODEL_TABLE_2, FABRIC_TEST_SEMANTIC_MODEL_COLUMNS_2, FABRIC_TEST_SEMANTIC_MODEL_SCHEMA
• Dataflow: FABRIC_TEST_DATAFLOW_NAME
• Azure SPN auth (when not using az login): AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
• Power BI tuning: POWERBI_BASE_URL, POWERBI_SCOPES, POWERBI_API_CALL_TIMEOUT, POWERBI_REFRESH_POLL_INTERVAL, POWERBI_REFRESH_WAIT_TIMEOUT

Run integration tests:

FABRIC_INTEGRATION_TESTS=1 pytest -m integration

Or filter to a specific test:

FABRIC_INTEGRATION_TESTS=1 pytest -m integration -k "copy_activity"

Notes:

• SQL tests require pyodbc and a SQL Server ODBC driver (Microsoft msodbcsql18 recommended). The CI workflow installs it via apt-get install msodbcsql18.
• Tests may skip when optional dependencies or environment variables are missing — this is intentional, not a failure.
• These tests use live Fabric resources and may incur capacity-usage and storage costs. Run against a non-production workspace.

Setup prerequisites for integration tests

The tests assume the following Fabric / Azure infrastructure is already in place. This setup is one-time per environment and is not part of the test run itself:

1. A dedicated Fabric workspace on an active capacity. Do not use a production workspace — the tests create, modify, and delete items.

2. A Lakehouse and a Warehouse in that workspace, with display names matching FABRIC_TEST_LAKEHOUSE_NAME and FABRIC_TEST_WAREHOUSE_NAME. The Lakehouse's SQL endpoint database name (which usually matches the Lakehouse name) goes in FABRIC_TEST_LAKEHOUSE_SQL_DATABASE.

3. Source databases reachable from Fabric (for Copy Activity tests). Options:

   • Azure-managed services (Azure SQL DB, Azure Database for PostgreSQL): create directly; Fabric reaches them over the public Azure backbone.
   • VM-hosted or on-premises databases: require an on-premises data gateway installed on a Windows host that can reach both the source database (on the source network) and Fabric (over the public internet).

4. Fabric connections to those source databases (one per source-engine you want to test). Create via Fabric portal → Settings → Manage connections and gateways → New connection. Use the Fabric REST API to read back the GUID for FABRIC_TEST_*_CONNECTION_ID:

   TOKEN=$(az account get-access-token --resource https://api.fabric.microsoft.com --query accessToken -o tsv)
   curl -sS -H "Authorization: Bearer $TOKEN" https://api.fabric.microsoft.com/v1/connections \
     | python3 -c "import json,sys
   for c in json.load(sys.stdin).get('value',[]):
       print(f\"{c['displayName']:40s} {c['id']}\")"
   

5. A Lakehouse-destination Fabric connection (Cloud > Lakehouse). Used for FABRIC_TEST_DEST_CONNECTION_ID. Pipeline Copy Activities target this connection when writing to the destination Lakehouse.

6. Auth:

   • Local development: az login as a Fabric workspace member is sufficient (the server uses DefaultAzureCredential).
   • CI / unattended: create an Azure service principal, add it to the test workspace as Member (Fabric portal → workspace → Manage access), grant it "Can use" on each Fabric connection (Settings → Manage connections → select connection → Share → add SP), and provide its credentials via AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET. Both ACL grants (workspace member + per-connection "Can use") are required — connection access does not inherit from workspace membership.

7. GitHub Actions (if running the bundled workflows): create an environment named Integration in your fork's repository settings and add every FABRIC_TEST_* and AZURE_* variable above as an environment secret with the same name. .github/workflows/integration-tests.yml lists the canonical secret-name set.

License

MIT