Skip to content
Back to search

Fabric-Analytics-MCP

A Model Context Protocol (MCP) server that enables AI assistants to securely access and analyze Microsoft Fabric Analytics data through authenticated API calls.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/santhoshravindran7--fabric-analytics-mcp/badge.svg)](/listings/santhoshravindran7--fabric-analytics-mcp)

HTML

<a href="/listings/santhoshravindran7--fabric-analytics-mcp"><img src="/api/listings/santhoshravindran7--fabric-analytics-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**🎯 Installation Methods**

Choose your preferred installation method:

**Option 1: Python Package (PyPI) ⭐ Recommended**

# Install via pip (easiest method)
pip install fabric-analytics-mcp

# Verify installation
fabric-analytics --version

# Start the server
fabric-analytics-mcp start

**Option 2: NPM Package**

# Install globally via npm
npm install -g mcp-for-microsoft-fabric-analytics

# Verify installation
fabric-analytics --version

# Start the server
fabric-analytics

# Or using npx (no installation required)
npx mcp-for-microsoft-fabric-analytics

**Option 3: Universal Installation Script**

For automated setup with environment configuration:

**Unix/Linux/macOS:**

# Download and run universal installer
curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash

# Or with options for full setup
curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash -s -- --method pip --config --env --test

**Windows (PowerShell):**

# Download and run Windows installer
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1'))

# Or with options for full setup
& ([scriptblock]::Create((iwr https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1).Content)) -Method pip -Config -Environment -Test

**Option 4: Docker**

# Clone repository
git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
cd Fabric-Analytics-MCP

# Build and run with Docker
docker build -t fabric-analytics-mcp .
docker run -d --name fabric-mcp -p 3000:3000 --env-file .env fabric-analytics-mcp

πŸ“– **See [Docker Installation Guide](scripts/DOCKER_INSTALL.md) for detailed Docker and Kubernetes deployment options.**

**Option 5: From Source (Development)**

# Clone and build from source
git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
cd Fabric-Analytics-MCP
npm install
npm run build    # βœ… All configuration files included!

**βš™οΈ Configuration**

Set up your environment variables:

export FABRIC_AUTH_METHOD=bearer_token  # or service_principal, interactive
export FABRIC_CLIENT_ID=your-client-id
export FABRIC_CLIENT_SECRET=your-client-secret
export FABRIC_TENANT_ID=your-tenant-id
export FABRIC_DEFAULT_WORKSPACE_ID=your-workspace-id

**πŸ”§ Claude Desktop Setup**

Add to your Claude Desktop config:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**For PyPI Installation:**

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "fabric-analytics-mcp",
      "args": ["start"],
      "env": {
        "FABRIC_AUTH_METHOD": "bearer_token"
      }
    }
  }
}

**For NPM Installation:**

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "fabric-analytics",
      "env": {
        "FABRIC_AUTH_METHOD": "bearer_token"
      }
    }
  }
}

**For Source Installation:**

{
  "mcpServers": {
    "fabric-analytics": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
    }
  }
}

**πŸš€ Start Using**

Restart Claude Desktop and try these queries: - *"List all workspaces I have access to"* - *"Find workspace named 'Analytics'"* - *"List all items in my Fabric workspace [your-workspace-id]"* - *"Create a new lakehouse called 'Analytics Hub'"* - *"Show me all running Spark applications"* - *"Execute this SQL query: SELECT * FROM my_table LIMIT 10"*

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,504 lines Β· 3 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <a href="https://glama.ai/mcp/servers/@santhoshravindran7/Fabric-Analytics-MCP">
  2. <img width="380" height="200" src="https://glama.ai/mcp/servers/@santhoshravindran7/Fabric-Analytics-MCP/badge" alt="Fabric Analytics MCP server" />
  3. </a>
  4. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/santhoshravindran7-fabric-analytics-mcp-badge.png)](https://mseep.ai/app/santhoshravindran7-fabric-analytics-mcp)
  5. # Microsoft Fabric Analytics MCP Server
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. [![PyPI version](https://badge.fury.io/py/fabric-analytics-mcp.svg)](https://badge.fury.io/py/fabric-analytics-mcp)
  8. [![npm version](https://badge.fury.io/js/mcp-for-microsoft-fabric-analytics.svg)](https://badge.fury.io/js/mcp-for-microsoft-fabric-analytics)
  9. [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
  10. [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
  11. [![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org/)
  12. [![Model Context Protocol](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
  13. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
  14. [![GitHub issues](https://img.shields.io/github/issues/santhoshravindran7/Fabric-Analytics-MCP.svg)](https://github.com/santhoshravindran7/Fabric-Analytics-MCP/issues)
  15. [![GitHub stars](https://img.shields.io/github/stars/santhoshravindran7/Fabric-Analytics-MCP.svg)](https://github.com/santhoshravindran7/Fabric-Analytics-MCP/stargazers)
  16. A comprehensive Model Context Protocol (MCP) server that provides analytics capabilities and tools for interacting with Microsoft Fabric data platform. This server enables AI assistants like Claude to seamlessly access, analyze, and monitor Microsoft Fabric resources through standardized MCP protocols, bringing the power of Microsoft Fabric directly to your AI conversations.
  17. ## πŸ“‹ **Table of Contents**
  18. - [🌟 Key Features](#-key-features)
  19. - [πŸš€ Quick Start](#-quick-start)
  20. - [πŸ› οΈ Tools & Capabilities](#️-tools--capabilities)
  21. - [πŸ§ͺ Development & Testing](#-development--testing)
  22. - [πŸ’¬ Example Queries](#-example-queries)
  23. - [πŸ” Authentication](#-authentication)
  24. - [πŸ—οΈ Architecture](#️-architecture)
  25. - [βš™οΈ Configuration](#️-configuration)
  26. - [🀝 Contributing](#-contributing)
  27. - [πŸ”’ Security](#-security)
  28. "Cancel the problematic Spark application"
  29. - [πŸ“ž Support](#-support)
  30. ## 🌟 **Key Features**
  31. - **πŸ—οΈ Complete Workspace Management** - Create, delete, and manage Fabric workspaces with capacity assignment
  32. - **πŸ”„ Enhanced CRUD Operations** - Create, read, update, and delete all Fabric items (notebooks, lakehouses, datasets, reports)
  33. - **πŸ““ Advanced Notebook Management** - Create, execute, and manage Fabric notebooks with 5 predefined templates
  34. - **⚑ Livy API Integration** - Full Spark session and batch job management with real-time monitoring
  35. - **πŸ“Š Comprehensive Spark Monitoring** - Real-time monitoring across workspaces, items, and applications
  36. - **πŸ€– Multi-AI Assistant Support** - Works with Claude Desktop, GitHub Copilot, and other MCP-compatible AI tools
  37. - **πŸ” Enhanced Azure CLI Authentication** - Zero-config setup with automatic token management
  38. - **�️ Enterprise Authentication** - Multiple auth methods (Bearer, Service Principal, Device Code, Interactive, Azure CLI)
  39. - **πŸ“ˆ Analytics & Insights** - Generate comprehensive monitoring dashboards with real-time metrics
  40. - **πŸ§ͺ End-to-End Testing** - Complete test suite with real workspace creation and job execution
  41. - **πŸ”„ Advanced Token Management** - Automatic token validation, refresh, and expiration handling
  42. "List all Fabric capacities I can use"
  43. "Assign workspace 1234abcd-abcd-1234-abcd-123456789000 to capacity f9998888-7777-6666-5555-444433332222"
  44. "Show all workspaces in capacity f9998888-7777-6666-5555-444433332222"
  45. "Unassign workspace 1234abcd-abcd-1234-abcd-123456789000 from its capacity"
  46. ```
  47. - **☸️ Enterprise Deployment** - Full Kubernetes and Azure deployment support with auto-scaling
  48. - **πŸ”„ Docker Support** - Containerized deployment with health checks and monitoring
  49. - **πŸ“Š Monitoring & Observability** - Built-in Prometheus metrics and Grafana dashboards
  50. - **πŸ”€ Synapse to Fabric Migration** - Automated migration of Spark notebooks from Azure Synapse Analytics
  51. - **🎯 52 Total Tools** - Comprehensive coverage of Fabric operations including migration (up from 48 tools)
  52. ## πŸ—οΈ **New Workspace Management Features**
  53. ### **πŸ†• Latest Updates - Comprehensive Workspace Operations**
  54. The MCP server now includes **21 new workspace management tools** that enable complete workspace lifecycle management:
  55. ### **🌟 Core Workspace Operations**
  56. - **fabric_list_workspaces** - List all accessible workspaces with detailed metadata
  57. - **fabric_create_workspace** - Create new workspaces with custom configuration
  58. - **fabric_delete_workspace** - Delete workspaces with confirmation and cleanup
  59. - **fabric_update_workspace** - Update workspace properties and settings
  60. - **fabric_get_workspace** - Get detailed workspace information and status
  61. ### **⚑ Capacity & Resource Management**
  62. - **fabric_list_capacities** - List all available Fabric capacities
  63. - **fabric_assign_workspace_to_capacity** - Attach workspaces to dedicated capacity
  64. - **fabric_unassign_workspace_from_capacity** - Move workspaces to shared capacity
  65. - **fabric_list_capacity_workspaces** - List all workspaces in a capacity
  66. ### **πŸ‘₯ Access Control & Security**
  67. - **fabric_get_workspace_role_assignments** - View workspace permissions
  68. - **fabric_add_workspace_role_assignment** - Grant workspace access to users/groups
  69. - **fabric_update_workspace_role_assignment** - Modify user permissions
  70. - **fabric_remove_workspace_role_assignment** - Remove workspace access
  71. ### **πŸ”„ Advanced Operations**
  72. - **fabric_get_workspace_git_status** - Check Git integration status
  73. - **fabric_connect_workspace_to_git** - Enable Git integration for workspace
  74. - **fabric_disconnect_workspace_from_git** - Disable Git integration
  75. - **fabric_update_workspace_git_connection** - Modify Git repository settings
  76. ### **πŸ› οΈ Environment & Pipeline Management**
  77. - **fabric_list_workspace_environments** - List all environments in workspace
  78. - **fabric_create_workspace_environment** - Create new environments
  79. - **fabric_delete_workspace_environment** - Remove environments
  80. - **fabric_list_workspace_data_pipelines** - List data integration pipelines
  81. - **fabric_create_workspace_data_pipeline** - Create new data pipelines
  82. ### **🎯 Real-World Scenarios Enabled**
  83. **πŸš€ Automated Workspace Provisioning:**
  84. ```
  85. "Create a new workspace called 'Analytics-Q1-2025' and assign it to our premium capacity"
  86. ```
  87. **πŸ“Š Multi-Workspace Analytics:**
  88. ```
  89. "List all workspaces in our tenant and show their capacity assignments"
  90. ```
  91. **πŸ”’ Access Management:**
  92. ```
  93. "Add user john.doe@company.com as Admin to the Analytics workspace"
  94. ```
  95. **πŸ—οΈ Environment Setup:**
  96. ```
  97. "Create a development environment in the Analytics workspace with Python and R libraries"
  98. ```
  99. **πŸ”„ Git Integration:**
  100. ```
  101. "Connect the Analytics workspace to our GitHub repository for version control"
  102. ```
  103. ### **πŸ€– GitHub Copilot Integration**
  104. **Perfect for GitHub Copilot** - The enhanced workspace management works seamlessly with **GitHub Copilot's built-in terminal**, making it ideal for:
  105. - **πŸ”§ Azure CLI Authentication** - Uses your existing `az login` session
  106. - **πŸ’» Terminal-Based Operations** - Natural workflow within your coding environment
  107. - **⚑ Rapid Prototyping** - Quickly create test workspaces and environments
  108. - **πŸ—οΈ Infrastructure as Code** - Manage Fabric resources alongside your codebase
  109. - **πŸ”„ CI/CD Integration** - Automate workspace provisioning in deployment pipelines
  110. **GitHub Copilot Example Commands:**
  111. ```bash
  112. # Using Azure CLI auth, create a new workspace for our ML project
  113. # List all workspaces and their Git integration status
  114. # Set up a complete analytics environment with lakehouse and notebooks
  115. ```
  116. ## πŸ”€ **Synapse to Fabric Migration Tools**
  117. ### **πŸ†• Automated Spark Workload Migration**
  118. The MCP server now includes **4 specialized migration tools** that automate the migration of Spark notebooks and pipelines from Azure Synapse Analytics to Microsoft Fabric:
  119. ### **πŸ” Migration Discovery Tools**
  120. - **fabric_list_synapse_workspaces** - List all Synapse workspaces in your Azure subscription
  121. - **fabric_discover_synapse_workspace** - Inventory notebooks, pipelines, linked services, and Spark jobs from Synapse
  122. ### **πŸ”„ Transformation & Migration Tools**
  123. - **fabric_transform_notebooks** - Transform Synapse notebooks to Fabric format (mssparkutils β†’ notebookutils)
  124. - **fabric_migrate_synapse_to_fabric** - Complete end-to-end migration with discovery, transformation, and provisioning
  125. ### **✨ Key Migration Features**
  126. - **Automatic Code Transformation** - Converts Synapse-specific code to Fabric equivalents:
  127. - `mssparkutils` β†’ `notebookutils`
  128. - Synapse magic commands β†’ Fabric magic commands
  129. - ABFSS path rewriting to OneLake
  130. - Spark pool configuration cleanup
  131. - **Comprehensive Asset Discovery** - Inventories all migrat assets:
  132. - Jupyter notebooks (ipynb format)
  133. - Data pipelines and workflows
  134. - Linked services and connections
  135. - Spark job definitions
  136. - **Safe Testing with Dry Run** - Preview all changes before applying:
  137. - Test transformations without provisioning
  138. - Validate transformed code
  139. - Review change reports
  140. - **End-to-End Automation** - Complete migration pipeline:
  141. - Discovery β†’ Transformation β†’ Provisioning β†’ Validation
  142. - Automatic lakehouse creation
  143. - OneLake shortcut provisioning
  144. - Comprehensive migration reports
  145. ### **🎯 Migration Scenarios**
  146. ![Migration Demo](docs/images/migration-demo.gif)
  147. **πŸ“‹ Explore Before Migrating:**
  148. ```
  149. "List all my Synapse workspaces and show me what notebooks are in workspace 'analytics-synapse'"
  150. ```
  151. **πŸ”„ Preview Transformations:**
  152. ```
  153. "Discover assets from my Synapse workspace 'analytics-synapse' and show me how the code would be transformed (dry run)"
  154. ```
  155. **πŸš€ Complete Migration:**
  156. ```
  157. "Migrate all notebooks from Synapse workspace 'analytics-synapse' to Fabric workspace 'abcd-1234' and create a lakehouse called 'MigratedData'"
  158. ```
  159. **πŸ“Š Detailed Migration Guide:**
  160. See [MIGRATION.md](./MIGRATION.md) for comprehensive migration documentation including:
  161. - Step-by-step workflows
  162. - Transformation rule details
  163. - Best practices and troubleshooting
  164. - Complete examples
  165. ### **🎯 End-to-End Testing with Real Workspaces**
  166. The MCP server now includes comprehensive end-to-end testing that creates real workspaces, assigns them to capacities, and executes actual jobs to validate the complete workflow:
  167. ```bash
  168. # One-command end-to-end test
  169. npm run test:e2e
  170. ```
  171. **What it tests:**
  172. - βœ… **Workspace Creation** - Creates real Fabric workspaces
  173. - βœ… **Capacity Assignment** - Attaches workspaces to your Fabric capacity
  174. - βœ… **Item Creation** - Creates notebooks, lakehouses, and other items
  175. - βœ… **Job Execution** - Runs actual Spark jobs and monitors completion
  176. - βœ… **Resource Cleanup** - Automatically removes all test resources
  177. ## πŸš€ **Deployment Options**
  178. ### **πŸ€– Claude Desktop Integration**
  179. **Recommended for AI Assistant Usage:**
  180. ```json
  181. {
  182. "mcpServers": {
  183. "fabric-analytics": {
  184. "command": "node",
  185. "args": ["C:\\path\\to\\your\\build\\index.js"],
  186. "cwd": "C:\\path\\to\\your\\project",
  187. "env": {
  188. "FABRIC_AUTH_METHOD": "bearer_token",
  189. "FABRIC_TOKEN": "your_bearer_token_here",
  190. "FABRIC_WORKSPACE_ID": "your_workspace_id",
  191. "ENABLE_HEALTH_SERVER": "false"
  192. }
  193. }
  194. }
  195. }
  196. ```
  197. > πŸ’‘ **Get Bearer Token:** Visit [Power BI Embed Setup](https://app.powerbi.com/embedsetup) to generate tokens
  198. >
  199. > ⚠️ **Important:** Tokens expire after ~1 hour and need to be refreshed
  200. #### **πŸ”§ Claude Desktop Authentication Fix**
  201. If you experience 60-second timeouts during startup, this is due to interactive authentication flows blocking Claude Desktop's sandboxed environment. **Solution:**
  202. 1. **Use Bearer Token Method** (Recommended):
  203. - Set `FABRIC_AUTH_METHOD: "bearer_token"` in your config
  204. - Provide `FABRIC_TOKEN` with a valid bearer token
  205. - This bypasses interactive authentication entirely
  206. 2. **Alternative - Per-Tool Authentication**:
  207. - Provide token directly in tool calls: `bearerToken: "your_token_here"`
  208. - Or use simulation mode: `bearerToken: "simulation"`
  209. 3. **Troubleshooting**:
  210. - Server now has 10-second timeout protection to prevent hanging
  211. - Falls back to simulation mode if authentication fails
  212. - Enhanced error messages provide clear guidance
  213. > 🎯 **Quick Fix**: The server automatically prioritizes `FABRIC_TOKEN` environment variable over interactive authentication flows, preventing Claude Desktop timeouts.
  214. ### **πŸ“± Local Development**
  215. ```bash
  216. # Clone and run locally
  217. git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
  218. cd Fabric-Analytics-MCP
  219. npm install && npm run build && npm start
  220. ```
  221. ### **🐳 Docker Deployment**
  222. ```bash
  223. # Using Docker Compose
  224. docker-compose up -d
  225. # Or standalone Docker
  226. docker build -t fabric-analytics-mcp .
  227. docker run -p 3000:3000 -e FABRIC_CLIENT_ID=xxx fabric-analytics-mcp
  228. ```
  229. ### **☸️ Azure Kubernetes Service (AKS)**
  230. ```bash
  231. # One-command enterprise deployment
  232. export ACR_NAME="your-registry" FABRIC_CLIENT_ID="xxx" FABRIC_CLIENT_SECRET="yyy" FABRIC_TENANT_ID="zzz"
  233. ./scripts/setup-azure-resources.sh && ./scripts/build-and-push.sh && ./scripts/deploy-to-aks.sh
  234. ```
  235. ### **🌐 Azure MCP Server (Preview)**
  236. ```bash
  237. # Serverless deployment on Azure
  238. az mcp server create --name "fabric-analytics-mcp" --repository "santhoshravindran7/Fabric-Analytics-MCP"
  239. ```
  240. **πŸ“š Detailed Guides**:
  241. - [🐳 Docker & Compose Setup](./docker-compose.yml)
  242. - [☸️ AKS Deployment Guide](./AKS_DEPLOYMENT.md)
  243. - [🌐 Azure MCP Server Guide](./AZURE_MCP_SERVER.md)
  244. - [πŸ”§ Configuration Examples](./.env.example)
  245. - [βœ… Deployment Validation](./scripts/validate-deployment.sh)
  246. ## πŸ› οΈ **Tools & Capabilities**
  247. ### πŸ” **CRUD Operations for Fabric Items**
  248. - **Tool**: `list-fabric-items`
  249. - **Description**: List items in a Microsoft Fabric workspace (Lakehouses, Notebooks, etc.)
  250. - **Parameters**:
  251. - `bearerToken`: Microsoft Fabric bearer token
  252. - `workspaceId`: Microsoft Fabric workspace ID
  253. - `itemType`: Filter by item type (optional)
  254. - **Tool**: `create-fabric-item`
  255. - **Description**: Create new items in Microsoft Fabric workspace
  256. - **Parameters**:
  257. - `bearerToken`: Microsoft Fabric bearer token
  258. - `workspaceId`: Microsoft Fabric workspace ID
  259. - `itemType`: Type of item (Lakehouse, Notebook, Dataset, Report, Dashboard)
  260. - `displayName`: Display name for the new item
  261. - `description`: Optional description
  262. - **Tool**: `get-fabric-item`
  263. - **Description**: Get detailed information about a specific Microsoft Fabric item
  264. - **Parameters**:
  265. - `bearerToken`: Microsoft Fabric bearer token
  266. - `workspaceId`: Microsoft Fabric workspace ID
  267. - `itemId`: ID of the item to retrieve
  268. - **Tool**: `update-fabric-item`
  269. - **Description**: Update existing items in Microsoft Fabric workspace
  270. - **Parameters**:
  271. - `bearerToken`: Microsoft Fabric bearer token
  272. - `workspaceId`: Microsoft Fabric workspace ID
  273. - `itemId`: ID of the item to update
  274. - `displayName`: New display name (optional)
  275. - `description`: New description (optional)
  276. - **Tool**: `delete-fabric-item`
  277. - **Description**: Delete items from Microsoft Fabric workspace
  278. - **Parameters**:
  279. - `bearerToken`: Microsoft Fabric bearer token
  280. - `workspaceId`: Microsoft Fabric workspace ID
  281. - `itemId`: ID of the item to delete
  282. ### πŸ” Query Fabric Dataset (Enhanced)
  283. - **Tool**: `query-fabric-dataset`
  284. - **Description**: Execute SQL or KQL queries against Microsoft Fabric datasets
  285. - **Parameters**:
  286. - `bearerToken`: Microsoft Fabric bearer token (optional - uses simulation if not provided)
  287. - `workspaceId`: Microsoft Fabric workspace ID
  288. - `datasetName`: Name of the dataset to query
  289. - `query`: SQL or KQL query to execute
  290. ### πŸš€ Execute Fabric Notebook
  291. - **Tool**: `execute-fabric-notebook`
  292. - **Description**: Execute a notebook in Microsoft Fabric workspace
  293. - **Parameters**:
  294. - `bearerToken`: Microsoft Fabric bearer token
  295. - `workspaceId`: Microsoft Fabric workspace ID
  296. - `notebookId`: ID of the notebook to execute
  297. - `parameters`: Optional parameters to pass to the notebook
  298. ### πŸ“Š Get Analytics Metrics
  299. - **Tool**: `get-fabric-metrics`
  300. - **Description**: Retrieve performance and usage metrics for Microsoft Fabric items
  301. - **Parameters**:
  302. - `workspaceId`: Microsoft Fabric workspace ID
  303. - `itemId`: Item ID (dataset, report, etc.)
  304. - `timeRange`: Time range for metrics (1h, 24h, 7d, 30d)
  305. - `metrics`: List of metrics to analyze
  306. ### πŸ”§ Analyze Data Model
  307. - **Tool**: `analyze-fabric-model`
  308. - **Description**: Analyze a Microsoft Fabric data model and get optimization recommendations
  309. - **Parameters**:
  310. - `workspaceId`: Microsoft Fabric workspace ID
  311. - `itemId`: Item ID to analyze
  312. ### πŸ“‹ Generate Analytics Report
  313. - **Tool**: `generate-fabric-report`
  314. - **Description**: Generate comprehensive analytics reports for Microsoft Fabric workspaces
  315. - **Parameters**:
  316. - `workspaceId`: Microsoft Fabric workspace ID
  317. - `reportType`: Type of report (performance, usage, health, summary)
  318. ### πŸš€ Livy API Integration (Sessions & Batch Jobs)
  319. #### Session Management
  320. - **Tool**: `create-livy-session`
  321. - **Description**: Create a new Livy session for interactive Spark/SQL execution
  322. - **Parameters**:
  323. - `bearerToken`: Microsoft Fabric bearer token
  324. - `workspaceId`: Microsoft Fabric workspace ID
  325. - `lakehouseId`: Microsoft Fabric lakehouse ID
  326. - `sessionConfig`: Optional session configuration
  327. - **Tool**: `get-livy-session`
  328. - **Description**: Get details of a Livy session
  329. - **Parameters**:
  330. - `bearerToken`: Microsoft Fabric bearer token
  331. - `workspaceId`: Microsoft Fabric workspace ID
  332. - `lakehouseId`: Microsoft Fabric lakehouse ID
  333. - `sessionId`: Livy session ID
  334. - **Tool**: `list-livy-sessions`
  335. - **Description**: List all Livy sessions in a lakehouse
  336. - **Parameters**:
  337. - `bearerToken`: Microsoft Fabric bearer token
  338. - `workspaceId`: Microsoft Fabric workspace ID
  339. - `lakehouseId`: Microsoft Fabric lakehouse ID
  340. - **Tool**: `delete-livy-session`
  341. - **Description**: Delete a Livy session
  342. - **Parameters**:
  343. - `bearerToken`: Microsoft Fabric bearer token
  344. - `workspaceId`: Microsoft Fabric workspace ID
  345. - `lakehouseId`: Microsoft Fabric lakehouse ID
  346. - `sessionId`: Livy session ID
  347. #### Statement Execution
  348. - **Tool**: `execute-livy-statement`
  349. - **Description**: Execute SQL or Spark statements in a Livy session
  350. - **Parameters**:
  351. - `bearerToken`: Microsoft Fabric bearer token
  352. - `workspaceId`: Microsoft Fabric workspace ID
  353. - `lakehouseId`: Microsoft Fabric lakehouse ID
  354. - `sessionId`: Livy session ID
  355. - `code`: SQL or Spark code to execute
  356. - `kind`: Statement type (sql, spark, etc.)
  357. - **Tool**: `get-livy-statement`
  358. - **Description**: Get status and results of a Livy statement
  359. - **Parameters**:
  360. - `bearerToken`: Microsoft Fabric bearer token
  361. - `workspaceId`: Microsoft Fabric workspace ID
  362. - `lakehouseId`: Microsoft Fabric lakehouse ID
  363. - `sessionId`: Livy session ID
  364. - `statementId`: Statement ID
  365. #### Batch Job Management
  366. - **Tool**: `create-livy-batch`
  367. - **Description**: Create a new Livy batch job for long-running operations
  368. - **Parameters**:
  369. - `bearerToken`: Microsoft Fabric bearer token
  370. - `workspaceId`: Microsoft Fabric workspace ID
  371. - `lakehouseId`: Microsoft Fabric lakehouse ID
  372. - `batchConfig`: Batch job configuration
  373. - **Tool**: `get-livy-batch`
  374. - **Description**: Get details of a Livy batch job
  375. - **Parameters**:
  376. - `bearerToken`: Microsoft Fabric bearer token
  377. - `workspaceId`: Microsoft Fabric workspace ID
  378. - `lakehouseId`: Microsoft Fabric lakehouse ID
  379. - `batchId`: Batch job ID
  380. - **Tool**: `list-livy-batches`
  381. - **Description**: List all Livy batch jobs in a lakehouse
  382. - **Parameters**:
  383. - `bearerToken`: Microsoft Fabric bearer token
  384. - `workspaceId`: Microsoft Fabric workspace ID
  385. - `lakehouseId`: Microsoft Fabric lakehouse ID
  386. - **Tool**: `delete-livy-batch`
  387. - **Description**: Delete a Livy batch job
  388. - **Parameters**:
  389. - `bearerToken`: Microsoft Fabric bearer token
  390. - `workspaceId`: Microsoft Fabric workspace ID
  391. - `lakehouseId`: Microsoft Fabric lakehouse ID
  392. - `batchId`: Batch job ID
  393. ### πŸ“Š Spark Application Monitoring
  394. #### Workspace-Level Monitoring
  395. - **Tool**: `get-workspace-spark-applications`
  396. - **Description**: Get all Spark applications in a Microsoft Fabric workspace
  397. - **Parameters**:
  398. - `bearerToken`: Microsoft Fabric bearer token
  399. - `workspaceId`: Microsoft Fabric workspace ID
  400. - `continuationToken`: Optional token for pagination
  401. #### Item-Specific Monitoring
  402. - **Tool**: `get-notebook-spark-applications`
  403. - **Description**: Get all Spark applications for a specific notebook
  404. - **Parameters**:
  405. - `bearerToken`: Microsoft Fabric bearer token
  406. - `workspaceId`: Microsoft Fabric workspace ID
  407. - `notebookId`: Notebook ID
  408. - `continuationToken`: Optional token for pagination
  409. - **Tool**: `get-lakehouse-spark-applications`
  410. - **Description**: Get all Spark applications for a specific lakehouse
  411. - **Parameters**:
  412. - `bearerToken`: Microsoft Fabric bearer token
  413. - `workspaceId`: Microsoft Fabric workspace ID
  414. - `lakehouseId`: Lakehouse ID
  415. - `continuationToken`: Optional token for pagination
  416. - **Tool**: `get-spark-job-definition-applications`
  417. - **Description**: Get all Spark applications for a specific Spark Job Definition
  418. - **Parameters**:
  419. - `bearerToken`: Microsoft Fabric bearer token
  420. - `workspaceId`: Microsoft Fabric workspace ID
  421. - `sparkJobDefinitionId`: Spark Job Definition ID
  422. - `continuationToken`: Optional token for pagination
  423. #### Application Management
  424. - **Tool**: `get-spark-application-details`
  425. - **Description**: Get detailed information about a specific Spark application
  426. - **Parameters**:
  427. - `bearerToken`: Microsoft Fabric bearer token
  428. - `workspaceId`: Microsoft Fabric workspace ID
  429. - `livyId`: Livy session ID
  430. - **Tool**: `cancel-spark-application`
  431. - **Description**: Cancel a running Spark application
  432. - **Parameters**:
  433. - `bearerToken`: Microsoft Fabric bearer token
  434. - `workspaceId`: Microsoft Fabric workspace ID
  435. - `livyId`: Livy session ID
  436. #### Monitoring Dashboard
  437. - **Tool**: `get-spark-monitoring-dashboard`
  438. - **Description**: Generate a comprehensive monitoring dashboard with analytics
  439. - **Parameters**:
  440. - `bearerToken`: Microsoft Fabric bearer token
  441. - `workspaceId`: Microsoft Fabric workspace ID
  442. ### πŸ““ **Notebook Management**
  443. The MCP server provides comprehensive notebook management capabilities with predefined templates and custom notebook support.
  444. #### Create Notebook from Template
  445. - **Tool**: `create-fabric-notebook`
  446. - **Description**: Create new Fabric notebooks from predefined templates or custom definitions
  447. - **Parameters**:
  448. - `bearerToken`: Microsoft Fabric bearer token
  449. - `workspaceId`: Microsoft Fabric workspace ID
  450. - `displayName`: Display name for the new notebook
  451. - `template`: Template type (blank, sales_analysis, nyc_taxi_analysis, data_exploration, machine_learning, custom)
  452. - `customNotebook`: Custom notebook definition (required if template is 'custom')
  453. - `environmentId`: Optional environment ID to attach
  454. - `lakehouseId`: Optional default lakehouse ID
  455. - `lakehouseName`: Optional default lakehouse name
  456. **Available Templates:**
  457. - **blank**: Basic notebook with minimal setup
  458. - **sales_analysis**: Comprehensive sales data analysis with sample dataset
  459. - **nyc_taxi_analysis**: NYC taxi trip data analysis with sample dataset
  460. - **data_exploration**: Structured data exploration template
  461. - **machine_learning**: Complete ML workflow template
  462. - **custom**: Use your own notebook definition
  463. #### Get Notebook Definition
  464. - **Tool**: `get-fabric-notebook-definition`
  465. - **Description**: Retrieve the notebook definition (cells, metadata) from an existing Fabric notebook
  466. - **Parameters**:
  467. - `bearerToken`: Microsoft Fabric bearer token
  468. - `workspaceId`: Microsoft Fabric workspace ID
  469. - `notebookId`: ID of the notebook to retrieve
  470. - `format`: Format to return (ipynb or fabricGitSource)
  471. #### Update Notebook Definition
  472. - **Tool**: `update-fabric-notebook-definition`
  473. - **Description**: Update the notebook definition (cells, metadata) of an existing Fabric notebook
  474. - **Parameters**:
  475. - `bearerToken`: Microsoft Fabric bearer token
  476. - `workspaceId`: Microsoft Fabric workspace ID
  477. - `notebookId`: ID of the notebook to update
  478. - `notebookDefinition`: Updated notebook definition object
  479. #### Execute Notebook
  480. - **Tool**: `run-fabric-notebook`
  481. - **Description**: Execute a Fabric notebook on-demand with optional parameters and configuration
  482. - **Parameters**:
  483. - `bearerToken`: Microsoft Fabric bearer token
  484. - `workspaceId`: Microsoft Fabric workspace ID
  485. - `notebookId`: ID of the notebook to run
  486. - `parameters`: Optional notebook parameters (key-value pairs with types)
  487. - `configuration`: Optional execution configuration (environment, lakehouse, pools, etc.)
  488. **Features:**
  489. - πŸ““ Base64 encoded notebook payload support
  490. - πŸ”§ Comprehensive metadata management
  491. - 🌐 Environment and lakehouse integration
  492. - πŸŽ›οΈ Parameterized notebook execution
  493. - ⚑ Spark configuration support
  494. - πŸ”€ Support for multiple programming languages (Python, Scala, SQL, R)
  495. ## πŸš€ **Quick Start**
  496. ### **🎯 Installation Methods**
  497. Choose your preferred installation method:
  498. #### **Option 1: Python Package (PyPI) ⭐ Recommended**
  499. ```bash
  500. # Install via pip (easiest method)
  501. pip install fabric-analytics-mcp
  502. # Verify installation
  503. fabric-analytics --version
  504. # Start the server
  505. fabric-analytics-mcp start
  506. ```
  507. #### **Option 2: NPM Package**
  508. ```bash
  509. # Install globally via npm
  510. npm install -g mcp-for-microsoft-fabric-analytics
  511. # Verify installation
  512. fabric-analytics --version
  513. # Start the server
  514. fabric-analytics
  515. # Or using npx (no installation required)
  516. npx mcp-for-microsoft-fabric-analytics
  517. ```
  518. #### **Option 3: Universal Installation Script**
  519. For automated setup with environment configuration:
  520. **Unix/Linux/macOS:**
  521. ```bash
  522. # Download and run universal installer
  523. curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 636 on GitHub
  524. # Or with options for full setup
  525. curl -fsSL https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-universal.sh | bash -s -- --method pip --config --env --test
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 639 on GitHub
  526. ```
  527. **Windows (PowerShell):**
  528. ```powershell
  529. # Download and run Windows installer
  530. iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1'))
  531. # Or with options for full setup
  532. & ([scriptblock]::Create((iwr https://raw.githubusercontent.com/santhoshravindran7/Fabric-Analytics-MCP/main/scripts/install-windows.ps1).Content)) -Method pip -Config -Environment -Test
  533. ```
  534. #### **Option 4: Docker**
  535. ```bash
  536. # Clone repository
  537. git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
  538. cd Fabric-Analytics-MCP
  539. # Build and run with Docker
  540. docker build -t fabric-analytics-mcp .
  541. docker run -d --name fabric-mcp -p 3000:3000 --env-file .env fabric-analytics-mcp
  542. ```
  543. πŸ“– **See [Docker Installation Guide](scripts/DOCKER_INSTALL.md) for detailed Docker and Kubernetes deployment options.**
  544. #### **Option 5: From Source (Development)**
  545. ```bash
  546. # Clone and build from source
  547. git clone https://github.com/santhoshravindran7/Fabric-Analytics-MCP.git
  548. cd Fabric-Analytics-MCP
  549. npm install
  550. npm run build # βœ… All configuration files included!
  551. ```
  552. ### **βš™οΈ Configuration**
  553. Set up your environment variables:
  554. ```bash
  555. export FABRIC_AUTH_METHOD=bearer_token # or service_principal, interactive
  556. export FABRIC_CLIENT_ID=your-client-id
  557. export FABRIC_CLIENT_SECRET=your-client-secret
  558. export FABRIC_TENANT_ID=your-tenant-id
  559. export FABRIC_DEFAULT_WORKSPACE_ID=your-workspace-id
  560. ```
  561. ### **πŸ”§ Claude Desktop Setup**
  562. Add to your Claude Desktop config:
  563. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  564. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  565. #### **For PyPI Installation:**
  566. ```json
  567. {
  568. "mcpServers": {
  569. "fabric-analytics": {
  570. "command": "fabric-analytics-mcp",
  571. "args": ["start"],
  572. "env": {
  573. "FABRIC_AUTH_METHOD": "bearer_token"
  574. }
  575. }
  576. }
  577. }
  578. ```
  579. #### **For NPM Installation:**
  580. ```json
  581. {
  582. "mcpServers": {
  583. "fabric-analytics": {
  584. "command": "fabric-analytics",
  585. "env": {
  586. "FABRIC_AUTH_METHOD": "bearer_token"
  587. }
  588. }
  589. }
  590. }
  591. ```
  592. #### **For Source Installation:**
  593. ```json
  594. {
  595. "mcpServers": {
  596. "fabric-analytics": {
  597. "command": "node",
  598. "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
  599. }
  600. }
  601. }
  602. ```
  603. ### **πŸš€ Start Using**
  604. Restart Claude Desktop and try these queries:
  605. - *"List all workspaces I have access to"*
  606. - *"Find workspace named 'Analytics'"*
  607. - *"List all items in my Fabric workspace [your-workspace-id]"*
  608. - *"Create a new lakehouse called 'Analytics Hub'"*
  609. - *"Show me all running Spark applications"*
  610. - *"Execute this SQL query: SELECT * FROM my_table LIMIT 10"*
  611. ## πŸ§ͺ **Development & Testing**
  612. ### **Running the Server**
  613. ```bash
  614. npm start # Production mode
  615. npm run dev # Development mode with auto-reload
  616. ```
  617. ### **Testing Livy API Integration**
  618. For comprehensive testing of Spark functionality, install Python dependencies:
  619. ```bash
  620. pip install -r livy_requirements.txt
  621. ```
  622. **Available Test Scripts:**
  623. - `livy_api_test.ipynb` - Interactive notebook for step-by-step testing
  624. - `comprehensive_livy_test.py` - Full-featured test with error handling
  625. - `spark_monitoring_test.py` - Spark application monitoring tests
  626. - `mcp_spark_monitoring_demo.py` - MCP server integration demo
  627. ### **Claude Desktop Integration**
  628. Add this configuration to your Claude Desktop config file:
  629. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  630. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  631. ```json
  632. {
  633. "mcpServers": {
  634. "fabric-analytics": {
  635. "command": "node",
  636. "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
  637. }
  638. }
  639. }
  640. ```
  641. **πŸŽ‰ You're ready!** Restart Claude Desktop and start asking questions about your Microsoft Fabric data!
  642. ### Livy API Testing Setup
  643. For testing the Livy API functionality, additional Python dependencies are required:
  644. ```bash
  645. # Install Python dependencies for Livy API testing
  646. pip install -r livy_requirements.txt
  647. ```
  648. #### Available Test Scripts:
  649. - `livy_api_test.ipynb` - Interactive Jupyter notebook for step-by-step testing
  650. - `comprehensive_livy_test.py` - Full-featured test with error handling
  651. - `simple_livy_test.py` - Simple test following example patterns
  652. - `livy_batch_test.py` - Batch job testing capabilities
  653. - `spark_monitoring_test.py` - Spark application monitoring tests
  654. ## Usage
  655. ### Running the Server
  656. ```bash
  657. npm start
  658. ```
  659. ### Development Mode
  660. ```bash
  661. npm run dev
  662. ```
  663. ### Testing with Claude Desktop
  664. Add the following configuration to your Claude Desktop config file:
  665. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  666. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  667. ```json
  668. {
  669. "mcpServers": {
  670. "fabric-analytics": {
  671. "command": "node",
  672. "args": ["/ABSOLUTE/PATH/TO/PROJECT/build/index.js"]
  673. }
  674. }
  675. }
  676. ```
  677. ## πŸ’¬ **Example Queries**
  678. Once connected to Claude Desktop, you can ask natural language questions like:
  679. ### **CRUD Operations:**
  680. - "List all Lakehouses in my workspace"
  681. - "Create a new Notebook called 'Data Analysis'"
  682. - "Update the description of my lakehouse"
  683. - "Delete the test notebook from my workspace"
  684. ### **Notebook Management:**
  685. - "Create a sales analysis notebook with sample data"
  686. - "Generate a new NYC taxi analysis notebook"
  687. - "Create a machine learning notebook template"
  688. - "Get the definition of my existing notebook"
  689. - "Run my notebook with specific parameters"
  690. - "Update my notebook with new cells"
  691. ### **Data Operations:**
  692. - "Query the sales dataset to get total revenue by region"
  693. - "Execute my analytics notebook with today's date"
  694. ### **Analytics:**
  695. - "Get performance metrics for the last 24 hours"
  696. - "Analyze my data model and provide optimization recommendations"
  697. - "Generate a usage report for my workspace"
  698. ### **Livy API Operations:**
  699. - "Create a Livy session for interactive Spark analysis"
  700. - "Execute SQL query 'SELECT * FROM my_table LIMIT 10'"
  701. - "Run Spark code to show all tables"
  702. - "Monitor my batch job progress"
  703. ### **Spark Application Monitoring:**
  704. - "Show me all Spark applications in my workspace"
  705. - "What's the status of my notebook Spark jobs?"
  706. - "Generate a comprehensive Spark monitoring dashboard"
  707. - "Show me recent failed applications"
  708. - "Cancel the problematic Spark application"
  709. ### **Capacity Management:**
  710. - "List all Fabric capacities I can use"
  711. - "Assign workspace 1234abcd-abcd-1234-abcd-123456789000 to capacity f9998888-7777-6666-5555-444433332222"
  712. - "Show all workspaces in capacity f9998888-7777-6666-5555-444433332222"
  713. - "Unassign workspace 1234abcd-abcd-1234-abcd-123456789000 from its capacity"
  714. ## 🧩 **Capacity Management Tools**
  715. Manage Microsoft Fabric capacity assignments directly from your AI assistant. These tools let you inspect available capacities, attach/detach workspaces, and audit capacity usage.
  716. ### Available Tools
  717. - `fabric_list_capacities` – Enumerate all capacities you can access (ID, SKU, region, state)
  718. - `fabric_assign_workspace_to_capacity` – Attach a workspace to a dedicated capacity
  719. - `fabric_unassign_workspace_from_capacity` – Return a workspace to shared capacity
  720. - `fabric_list_capacity_workspaces` – List all workspaces currently hosted on a given capacity
  721. ### Notes
  722. - If authentication fails or you're in simulation mode, capacity responses are simulated.
  723. - Real capacity operations require appropriate Fabric / Power BI admin permissions.
  724. - You can provide a bearer token per call (`bearerToken` field) or rely on global auth.
  725. ### Minimal Parameter Reference
  726. | Tool | Required Parameters | Optional |
  727. |------|---------------------|----------|
  728. | fabric_list_capacities | (none) | bearerToken |
  729. | fabric_assign_workspace_to_capacity | capacityId, workspaceId | bearerToken |
  730. | fabric_unassign_workspace_from_capacity | workspaceId | bearerToken |
  731. | fabric_list_capacity_workspaces | capacityId | bearerToken |
  732. ## ❗ **Troubleshooting**
  733. ### JSON Parse Errors (e.g., `Unexpected token 'P'`)
  734. If Claude Desktop or another MCP client reports an error like:
  735. ```
  736. Error: Unexpected token 'P', "Please set"... is not valid JSON
  737. SyntaxError: Unexpected token 'P', "Please set"... is not valid JSON
  738. ```
  739. **This is the EXACT issue reported in GitHub issue where the user saw "Unexpected token 'P', 'Please set'..." errors.**
  740. This almost always means something wrote plain text to STDOUT (which must contain ONLY JSON-RPC frames). Common causes:
  741. 1. Added `console.log` debug statements in server code
  742. 2. A dependency emitting warnings to STDOUT
  743. 3. Early logging before transport initialization
  744. ### Fixes Implemented in This Server
  745. - βœ… A startup guard now redirects `console.log` / `console.info` to STDERR automatically
  746. - βœ… Debug output has been consolidated behind the `DEBUG_MCP_RUN=1` flag
  747. - βœ… All diagnostic messages go to STDERR, keeping STDOUT clean for JSON-RPC protocol
  748. ### What You Can Do
  749. - Avoid adding raw `console.log` statementsβ€”prefer `console.error` (goes to STDERR)
  750. - If you must allow stdout logging temporarily (NOT recommended), set:
  751. - `ALLOW_UNSAFE_STDOUT=true`
  752. - Remove after debugging
  753. - Regenerate the build (`npm run build`) after changes to ensure compiled output matches source
  754. ### Capacity Tools Not Appearing?
  755. If the capacity tools don't show up when the client lists tools:
  756. 1. Ensure you rebuilt after pulling changes: `npm run build`
  757. 2. Confirm you're launching the server from `build/index.js` and not an older snapshot
  758. 3. Verify no MCP client-side allowlist is filtering tool names
  759. 4. Run a quick enumeration test: ask the assistant "List all available tools"
  760. 5. If still missing, delete the `build/` folder and rebuild to clear stale artifacts
  761. ### Authentication Edge Cases
  762. - Azure CLI auth may fail silently without an active `az login` session
  763. - Bearer tokens expire (~1 hour); refresh if operations suddenly fail
  764. - For local testing: falling back to simulation still lets you prototype tool flows
  765. ### Getting Verbose Diagnostics
  766. Set the following (sent to STDERR, safe for MCP framing):
  767. ```
  768. DEBUG_MCP_RUN=1
  769. ```
  770. Optionally add structured auth tracing:
  771. ```
  772. DEBUG_AUTH=1
  773. ```
  774. ---
  775. **Need a new troubleshooting topic?** Open an issue or PR so others benefit from the resolution.
  776. ### **πŸ” Authentication**
  777. This MCP server supports **multiple authentication methods** powered by Microsoft Authentication Library (MSAL):
  778. > **πŸ€– For Claude Desktop:** Use Bearer Token Authentication (Method #1) for the best experience and compatibility.
  779. >
  780. > **πŸ”§ Claude Desktop Fix:** Recent updates prevent authentication timeouts by prioritizing bearer tokens and adding timeout protection for interactive authentication flows.
  781. #### **🎫 1. Bearer Token Authentication** (Recommended for Claude Desktop)
  782. Perfect for AI assistants and interactive usage:
  783. **For Claude Desktop:**
  784. - Visit [Power BI Embed Setup](https://app.powerbi.com/embedsetup)
  785. - Generate a bearer token for your workspace
  786. - Add to your `claude_desktop_config.json`
  787. - **No timeout issues** - bypasses interactive authentication entirely
  788. **For Testing:**
  789. ```bash
  790. # All test scripts will prompt for authentication method
  791. python enhanced_auth_test.py
  792. ```
  793. #### **πŸ€– 2. Service Principal Authentication** (Recommended for Production)
  794. Use Azure AD application credentials:
  795. - **Client ID** (Application ID)
  796. - **Client Secret**
  797. - **Tenant ID** (Directory ID)
  798. **Environment Variables Setup**:
  799. ```bash
  800. export FABRIC_AUTH_METHOD="service_principal"
  801. export FABRIC_CLIENT_ID="your-app-client-id"
  802. export FABRIC_CLIENT_SECRET="your-app-client-secret"
  803. export FABRIC_TENANT_ID="your-tenant-id"
  804. export FABRIC_DEFAULT_WORKSPACE_ID="your-workspace-id"
  805. ```
  806. **Claude Desktop Configuration**:
  807. ```json
  808. {
  809. "mcpServers": {
  810. "fabric-analytics": {
  811. "command": "node",
  812. "args": ["/path/to/build/index.js"],
  813. "env": {
  814. "FABRIC_AUTH_METHOD": "service_principal",
  815. "FABRIC_CLIENT_ID": "your-client-id",
  816. "FABRIC_CLIENT_SECRET": "your-client-secret",
  817. "FABRIC_TENANT_ID": "your-tenant-id"
  818. }
  819. }
  820. }
  821. }
  822. ```
  823. #### **πŸ“± 3. Device Code Authentication**
  824. Sign in with browser on another device (great for headless environments):
  825. ```bash
  826. export FABRIC_AUTH_METHOD="device_code"
  827. export FABRIC_CLIENT_ID="your-client-id"
  828. export FABRIC_TENANT_ID="your-tenant-id"
  829. ```
  830. #### **🌐 4. Interactive Authentication**
  831. Automatic browser-based authentication:
  832. ```bash
  833. export FABRIC_AUTH_METHOD="interactive"
  834. export FABRIC_CLIENT_ID="your-client-id"
  835. export FABRIC_TENANT_ID="your-tenant-id"
  836. ```
  837. #### **πŸ”§ 5. Azure CLI Authentication** ⭐ **(Recommended for Local Development)**
  838. Use your existing Azure CLI login for seamless local testing:
  839. ```bash
  840. export FABRIC_AUTH_METHOD="azure_cli"
  841. ```
  842. **Prerequisites**:
  843. 1. Install Azure CLI: `winget install Microsoft.AzureCLI` (Windows) or [Download](https://aka.ms/installazurecliwindows)
  844. 2. Login to Azure: `az login`
  845. 3. Set active subscription: `az account set --subscription "your-subscription-name"`
  846. **Benefits**:
  847. - βœ… **Zero Configuration** - Uses your existing Azure login
  848. - βœ… **Instant Setup** - No app registration or client secrets needed
  849. - βœ… **Multi-Account Support** - Switch Azure accounts easily
  850. - βœ… **Perfect for Development** - Seamless local testing experience
  851. **Quick Test**:
  852. ```powershell
  853. # Verify Azure CLI setup
  854. npm run test:azure-cli
  855. # Start MCP server with Azure CLI auth
  856. $env:FABRIC_AUTH_METHOD="azure_cli"; npm start
  857. ```
  858. > πŸ’‘ **Pro Tip**: Azure CLI authentication is perfect for developers who want to quickly test the MCP server without complex Azure AD app setup. Just `az login` and you're ready to go!
  859. #### **πŸ”§ Complete Authentication Setup**
  860. πŸ“š **Detailed Guides**:
  861. - **[Authentication Setup Guide](AUTHENTICATION_SETUP.md)** - Complete Azure AD setup
  862. - **[Claude Desktop Config Examples](CLAUDE_DESKTOP_CONFIG_EXAMPLES.md)** - Ready-to-use configurations
  863. #### **πŸ” Authentication Testing**
  864. Check your authentication status:
  865. ```
  866. "Check my Fabric authentication status"
  867. "What authentication method am I using?"
  868. "Test my Microsoft Fabric authentication setup"
  869. ```
  870. #### **πŸ”’ Security Best Practices**
  871. - **Never commit authentication tokens** to version control
  872. - Use **Service Principal** authentication for production deployments
  873. - **Device Code** flow is perfect for CI/CD and headless environments
  874. - **Interactive** authentication is ideal for development and testing
  875. - All tokens are automatically validated and include expiration checking
  876. **Note**: The MCP server seamlessly handles token validation and provides clear error messages for authentication issues.
  877. ## ☸️ **Azure Kubernetes Service (AKS) Deployment**
  878. Deploy the MCP server as a scalable service on Azure Kubernetes Service for enterprise production use.
  879. ### **πŸš€ Quick AKS Deployment**
  880. #### **Prerequisites**
  881. - Azure CLI installed and configured
  882. - Docker installed
  883. - kubectl installed
  884. - Azure subscription with AKS permissions
  885. #### **1. Build and Push Docker Image**
  886. ```bash
  887. # Build the Docker image
  888. npm run docker:build
  889. # Tag and push to Azure Container Registry
  890. npm run docker:push
  891. ```
  892. #### **2. Deploy to AKS**
  893. ```bash
  894. # Create Azure resources and deploy
  895. ./scripts/deploy-to-aks.sh
  896. ```
  897. #### **3. Access the MCP Server**
  898. Once deployed, your MCP server will be available at:
  899. ```
  900. https://your-aks-cluster.region.cloudapp.azure.com/mcp
  901. ```
  902. ### **πŸ—οΈ Architecture Overview**
  903. The AKS deployment includes:
  904. - **Horizontal Pod Autoscaler** (3-10 pods based on CPU/memory)
  905. - **Azure Load Balancer** for high availability
  906. - **SSL/TLS termination** with Azure Application Gateway
  907. - **ConfigMaps** for environment configuration
  908. - **Secrets** for secure credential storage
  909. - **Health checks** and readiness probes
  910. - **Resource limits** and quality of service guarantees
  911. ### **πŸ“ Deployment Files**
  912. All Kubernetes manifests are located in the `/k8s` directory:
  913. - `namespace.yaml` - Dedicated namespace
  914. - `deployment.yaml` - Application deployment with scaling
  915. - `service.yaml` - Load balancer service
  916. - `ingress.yaml` - External access and SSL
  917. - `configmap.yaml` - Configuration management
  918. - `secret.yaml` - Secure credential storage
  919. - `hpa.yaml` - Horizontal Pod Autoscaler
  920. ### **πŸ”§ Configuration**
  921. Configure the deployment by setting these environment variables:
  922. ```bash
  923. export AZURE_SUBSCRIPTION_ID="your-subscription-id"
  924. export AZURE_RESOURCE_GROUP="fabric-mcp-rg"
  925. export AKS_CLUSTER_NAME="fabric-mcp-cluster"
  926. export ACR_NAME="fabricmcpregistry"
  927. export DOMAIN_NAME="your-domain.com"
  928. ```
  929. ### **πŸ” Production Security**
  930. The AKS deployment includes enterprise-grade security:
  931. - **Non-root container** execution
  932. - **Read-only root filesystem**
  933. - **Secret management** via Azure Key Vault integration
  934. - **Network policies** for traffic isolation
  935. - **RBAC** with minimal required permissions
  936. - **Pod security standards** enforcement
  937. ### **πŸ“Š Monitoring & Scaling**
  938. - **Azure Monitor** integration for logs and metrics
  939. - **Application Insights** for performance monitoring
  940. - **Prometheus** metrics endpoint for custom monitoring
  941. - **Auto-scaling** based on CPU (70%) and memory (80%) thresholds
  942. - **Health checks** for automatic pod restart
  943. ### **πŸ”„ CI/CD Integration**
  944. The deployment scripts support:
  945. - **Azure DevOps** pipelines
  946. - **GitHub Actions** workflows
  947. - **Automated testing** before deployment
  948. - **Blue-green deployments** for zero downtime
  949. - **Rollback capabilities** for quick recovery
  950. **πŸ“š Detailed Guide**: See [AKS_DEPLOYMENT.md](AKS_DEPLOYMENT.md) for complete setup instructions.
  951. ## 🌐 **Azure Model Context Protocol Server (Preview)**
  952. Microsoft Azure now offers a preview service for hosting MCP servers natively. This eliminates the need for custom infrastructure management.
  953. ### **πŸš€ Azure MCP Server Deployment**
  954. #### **Prerequisites**
  955. - Azure subscription with MCP preview access
  956. - Azure CLI with MCP extensions
  957. #### **Deploy to Azure MCP Service**
  958. ```bash
  959. # Login to Azure
  960. az login
  961. # Enable MCP preview features
  962. az extension add --name mcp-preview
  963. # Deploy the MCP server
  964. az mcp server create \
  965. --name "fabric-analytics-mcp" \
  966. --resource-group "your-rg" \
  967. --source-type "github" \
  968. --repository "santhoshravindran7/Fabric-Analytics-MCP" \
  969. --branch "main" \
  970. --auth-method "service-principal"
  971. ```
  972. #### **Configure Authentication**
  973. ```bash
  974. # Set up service principal authentication
  975. az mcp server config set \
  976. --name "fabric-analytics-mcp" \
  977. --setting "FABRIC_CLIENT_ID=your-client-id" \
  978. --setting "FABRIC_CLIENT_SECRET=your-secret" \
  979. --setting "FABRIC_TENANT_ID=your-tenant-id"
  980. ```
  981. #### **Access Your MCP Server**
  982. ```bash
  983. # Get the server endpoint
  984. az mcp server show --name "fabric-analytics-mcp" --query "endpoint"
  985. ```
  986. ### **πŸ”§ Azure MCP Server Features**
  987. - **Automatic scaling** based on usage
  988. - **Built-in monitoring** and logging
  989. - **Integrated security** with Azure AD
  990. - **Zero infrastructure management**
  991. - **Global CDN** for low latency
  992. - **Automatic SSL/TLS** certificates
  993. ### **πŸ’° Cost Optimization**
  994. Azure MCP Server offers:
  995. - **Pay-per-request** pricing model
  996. - **Automatic hibernation** during idle periods
  997. - **Resource sharing** across multiple clients
  998. - **No minimum infrastructure costs**
  999. **πŸ“š Learn More**: [Azure MCP Server Documentation](https://docs.microsoft.com/azure/mcp-server/)
  1000. **Note**: Azure MCP Server is currently in preview. Check [Azure Preview Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for service availability and limitations.
  1001. ## πŸ—οΈ **Architecture**
  1002. This MCP server is built with:
  1003. - **TypeScript** for type-safe development
  1004. - **MCP SDK** for Model Context Protocol implementation
  1005. - **Zod** for schema validation and input sanitization
  1006. - **Node.js** runtime environment
  1007. ## βš™οΈ **Configuration**
  1008. The server uses the following configuration files:
  1009. - `tsconfig.json` - TypeScript compiler configuration
  1010. - `package.json` - Node.js package configuration
  1011. - `.vscode/mcp.json` - MCP server configuration for VS Code
  1012. ## πŸ”§ **Development**
  1013. ### **Project Structure**
  1014. ```
  1015. β”œβ”€β”€ src/
  1016. β”‚ β”œβ”€β”€ index.ts # Main MCP server implementation
  1017. β”‚ └── fabric-client.ts # Microsoft Fabric API client
  1018. β”œβ”€β”€ build/ # Compiled JavaScript output
  1019. β”œβ”€β”€ tests/ # Test scripts and notebooks
  1020. β”œβ”€β”€ .vscode/ # VS Code configuration
  1021. β”œβ”€β”€ package.json
  1022. β”œβ”€β”€ tsconfig.json
  1023. └── README.md
  1024. ```
  1025. ### **Adding New Tools**
  1026. To add new tools to the server:
  1027. 1. Define the input schema using Zod
  1028. 2. Implement the tool using `server.tool()`
  1029. 3. Add error handling and validation
  1030. 4. Update documentation
  1031. ### **API Integration**
  1032. This server includes:
  1033. **βœ… Production Ready:**
  1034. - Full Microsoft Fabric Livy API integration
  1035. - Spark session lifecycle management
  1036. - Statement execution with SQL and Spark support
  1037. - Batch job management for long-running operations
  1038. - Comprehensive error handling and retry logic
  1039. - Real-time polling and result retrieval
  1040. **πŸ§ͺ Demonstration Features:**
  1041. - CRUD operations (configurable for real APIs)
  1042. - Analytics and metrics (extensible framework)
  1043. - Data model analysis (template implementation)
  1044. ## πŸ§ͺ **Testing**
  1045. ### **πŸš€ End-to-End Testing**
  1046. The MCP server includes comprehensive end-to-end testing that creates real workspaces, items, and jobs to validate complete functionality using Azure CLI authentication.
  1047. #### **Quick Setup for E2E Testing**
  1048. ```bash
  1049. # 1. Set up end-to-end testing environment
  1050. npm run setup:e2e
  1051. # 2. Run the comprehensive end-to-end test
  1052. npm run test:e2e
  1053. ```
  1054. #### **What the E2E Test Does**
  1055. The end-to-end test creates a complete workflow in your Microsoft Fabric tenant:
  1056. 1. **πŸ” Validates Azure CLI Authentication** - Uses your existing `az login` session
  1057. 2. **πŸ—οΈ Creates a Test Workspace** - New workspace with unique naming
  1058. 3. **⚑ Attaches to Capacity** - Links workspace to your Fabric capacity (optional)
  1059. 4. **πŸ““ Creates Notebooks & Lakehouses** - Test items for validation
  1060. 5. **πŸƒ Runs Real Jobs** - Executes notebook with actual Spark code
  1061. 6. **πŸ“Š Monitors Execution** - Tracks job status and completion
  1062. 7. **🧹 Cleans Up Resources** - Removes all created test resources
  1063. #### **E2E Test Configuration**
  1064. The setup script creates a `.env.e2e` configuration file:
  1065. ```bash
  1066. # Example configuration
  1067. FABRIC_CAPACITY_ID=your-capacity-id-here # Optional: for capacity testing
  1068. E2E_TEST_TIMEOUT=300000 # 5 minutes per operation
  1069. E2E_CLEANUP_ON_FAILURE=true # Clean up on test failure
  1070. E2E_RETRY_COUNT=3 # Retry failed operations
  1071. ```
  1072. #### **E2E Test Features**
  1073. - βœ… **Real Resource Creation** - Creates actual Fabric workspaces and items
  1074. - βœ… **Azure CLI Integration** - Uses your existing Azure authentication
  1075. - βœ… **Capacity Assignment** - Tests workspace-to-capacity attachment
  1076. - βœ… **Job Execution** - Runs real Spark jobs and monitors completion
  1077. - βœ… **Automatic Cleanup** - Removes all test resources automatically
  1078. - βœ… **Comprehensive Logging** - Detailed logging of all operations
  1079. - βœ… **Error Handling** - Robust error handling and recovery
  1080. #### **Prerequisites for E2E Testing**
  1081. 1. **Azure CLI** installed and logged in:
  1082. ```bash
  1083. az login
  1084. ```
  1085. 2. **Microsoft Fabric Access** with permissions to:
  1086. - Create workspaces
  1087. - Create notebooks and lakehouses
  1088. - Run Spark jobs
  1089. - (Optional) Assign workspaces to capacity
  1090. 3. **Fabric Capacity** (optional but recommended):
  1091. - Set `FABRIC_CAPACITY_ID` in `.env.e2e` for capacity testing
  1092. - Without capacity, workspace will use shared capacity
  1093. #### **Running E2E Tests**
  1094. ```bash
  1095. # Complete setup and run
  1096. npm run setup:e2e && npm run test:e2e
  1097. # Or run individual steps
  1098. npm run setup:e2e # Set up environment
  1099. npm run test:e2e # Run end-to-end test
  1100. # Direct execution
  1101. node setup-e2e.cjs # Setup script
  1102. node test-end-to-end.cjs # Test script
  1103. ```
  1104. #### **E2E Test Output**
  1105. The test provides comprehensive output including:
  1106. ```
  1107. πŸš€ Starting End-to-End Test for Microsoft Fabric Analytics MCP Server
  1108. βœ… MCP Server Startup (1234ms)
  1109. βœ… Azure CLI Authentication
  1110. βœ… Workspace Creation
  1111. βœ… Capacity Attachment
  1112. βœ… Notebook Creation
  1113. βœ… Lakehouse Creation
  1114. βœ… Item Validation
  1115. βœ… Job Execution
  1116. πŸ“Š TEST SUMMARY
  1117. ================
  1118. βœ… MCP Server Startup (2341ms)
  1119. βœ… Azure CLI Authentication
  1120. βœ… Workspace Creation
  1121. βœ… Capacity Attachment
  1122. βœ… Notebook Creation
  1123. βœ… Lakehouse Creation
  1124. βœ… Item Validation
  1125. βœ… Job Execution
  1126. Total: 8 | Passed: 8 | Failed: 0
  1127. ```
  1128. #### **⚠️ Important Notes for E2E Testing**
  1129. - **Creates Real Resources**: The test creates actual workspaces and items in your Fabric tenant
  1130. - **Requires Permissions**: Ensure you have necessary Fabric permissions
  1131. - **Uses Capacity**: Jobs may consume capacity units if using dedicated capacity
  1132. - **Automatic Cleanup**: All resources are automatically deleted after testing
  1133. - **Network Dependent**: Requires stable internet connection for API calls
  1134. ### **πŸ§ͺ Unit & Integration Testing**
  1135. ### **Prerequisites**
  1136. ```bash
  1137. # Install Python dependencies for API testing
  1138. pip install -r livy_requirements.txt
  1139. ```
  1140. ### **Available Test Scripts**
  1141. - `livy_api_test.ipynb` - Interactive Jupyter notebook for step-by-step testing
  1142. - `comprehensive_livy_test.py` - Full-featured test with error handling
  1143. - `simple_livy_test.py` - Simple test following example patterns
  1144. - `livy_batch_test.py` - Batch job testing capabilities
  1145. - `spark_monitoring_test.py` - Spark application monitoring tests
  1146. ### **Quick Testing**
  1147. 1. **Interactive Testing**:
  1148. ```bash
  1149. jupyter notebook livy_api_test.ipynb
  1150. ```
  1151. 2. **Command Line Testing**:
  1152. ```bash
  1153. python simple_livy_test.py
  1154. python spark_monitoring_test.py
  1155. ```
  1156. 3. **Comprehensive Testing**:
  1157. ```bash python comprehensive_livy_test.py --auth bearer
  1158. ```
  1159. ## 🀝 **Contributing**
  1160. We welcome contributions! Here's how to get started:
  1161. 1. **Fork the repository**
  1162. 2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
  1163. 3. **Make your changes** and add tests if applicable
  1164. 4. **Commit your changes** (`git commit -m 'Add amazing feature'`)
  1165. 5. **Push to the branch** (`git push origin feature/amazing-feature`)
  1166. 6. **Open a Pull Request**
  1167. ### **Development Guidelines**
  1168. - Follow TypeScript best practices
  1169. - Add JSDoc comments for new functions
  1170. - Update tests for any new functionality
  1171. - Update documentation as needed
  1172. - See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines
  1173. ## πŸ”’ **Security**
  1174. - **Never commit authentication tokens** to version control
  1175. - Use environment variables for sensitive configuration
  1176. - Follow Microsoft Fabric security best practices
  1177. - Report security issues privately via [GitHub security advisories](https://github.com/santhoshravindran7/Fabric-Analytics-MCP/security/advisories)
  1178. - See [SECURITY.md](SECURITY.md) for our full security policy
  1179. ## πŸ“ **License**
  1180. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  1181. ## **Support**
  1182. For issues and questions:
  1183. - πŸ“– Check the [MCP documentation](https://modelcontextprotocol.io/)
  1184. - πŸ“š Review [Microsoft Fabric API documentation](https://docs.microsoft.com/en-us/fabric/)
  1185. - πŸ› [Open an issue](https://github.com/santhoshravindran7/Fabric-Analytics-MCP/issues) in this repository
  1186. - πŸ’¬ Join the community discussions
  1187. ## **Acknowledgments**
  1188. - **Microsoft Fabric Analytics team** for the comprehensive data platform and analytics capabilities
  1189. - **Microsoft Fabric Platform teams** for the robust API platform and infrastructure
  1190. - **Bogdan Crivat** and **Chris Finlan** for the inspiring brainstorming conversation that gave me the idea to open-source this project
  1191. - **Anthropic** for the Model Context Protocol specification
  1192. *This project began as my weekend hack project exploring AI integration with Microsoft Fabric. During a casual conversation with Chris and Bogdan about making AI tooling more accessible. What started as a personal experiment over a weekend is now available for everyone to build upon.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.