MCP Fabric API

mcp织物api

用于Microsoft Fabric REST API的MCP（模型上下文协议）服务器。专为希望使用Copilot之外的AI助手（如Claude、Claude Code或任何兼容MCP的客户端）构建和管理其Fabric组件的数据工程师和数据分析师而设计。涵盖工作区、湖畔小屋、仓库、笔记本电脑、管道、语义模型、报告、数据流、事件库、事件流、反射、GraphQL API、SQL端点、变量库、git集成、部署管道、镜像数据库、KQL数据库、ML模型、ML实验、复制作业、外部数据共享和环境（Spark compute+库，带笔记本电脑连接/分离）。

默认安全： 此服务器阻止所有破坏性操作（创建、更新、删除），直到您明确配置 WRITABLE_WORKSPACES 环境变量。读取操作始终有效。设置 WRITABLE_WORKSPACES="*" 允许对所有工作区进行写入，或使用模式限制访问。看 工作区安全防护 了解详情。

先决条件

• Node.js 18+
• 访问Microsoft Fabric工作区
• 什么之中的一个：

- Azure命令行界面(az login)--在Windows上最简单 - 启用设备代码流的Azure应用程序注册——最适合Mac/Claude Desktop - 服务主体凭据——最适合无头/自动化场景

快速开始

Windows（Azure CLI）：

az login
npx @einlogic/mcp-fabric-api

Mac/Claude桌面（设备代码）：

AUTH_METHOD=device-code AZURE_CLIENT_ID=your-app-id AZURE_TENANT_ID=your-tenant-id npx @einlogic/mcp-fabric-api

在第一次API调用时，登录URL和代码将显示在日志中。在浏览器中打开URL，输入代码，然后进行身份验证。

设置

克劳德桌面版

添加到您的Claude Desktop配置文件中：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

Windows（使用Azure CLI凭据）：

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "@einlogic/mcp-fabric-api"]
    }
  }
}

macOS（使用设备代码流）：

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "@einlogic/mcp-fabric-api"],
      "env": {
        "AUTH_METHOD": "device-code",
        "AZURE_CLIENT_ID": "your-app-client-id",
        "AZURE_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

服务器启动时，检查Claude Desktop日志中的登录提示：

• macOS： ~/Library/Logs/Claude/mcp-server-fabric.log
• 窗户： %APPDATA%\Claude\logs\mcp-server-fabric.log

提示将显示： *“要登录，请使用web浏览器打开https://microsoft.com/devicelogin并输入代码XXXXXXX”*。完成一次登录，令牌将为会话缓存。

克劳德代码CLI

窗户：

claude mcp add fabric -- npx -y @einlogic/mcp-fabric-api

macOS：

claude mcp add fabric -e AUTH_METHOD=device-code -e AZURE_CLIENT_ID=your-app-id -e AZURE_TENANT_ID=your-tenant-id -- npx -y @einlogic/mcp-fabric-api

要验证是否已添加：

claude mcp list

HTTP模式（远程）

对于远程部署，设置环境变量：

export TRANSPORT=http
export PORT=3000
export AZURE_CLIENT_ID=your-client-id
export AZURE_CLIENT_SECRET=your-client-secret
export AZURE_TENANT_ID=your-tenant-id
npx @einlogic/mcp-fabric-api

服务器公开：

• POST /mcp --MCP端点（流式HTTP）
• GET /mcp --服务器通知的SSE流
• DELETE /mcp --会话清理
• GET /.well-known/oauth-protected-resource --OAuth元数据

身份验证方法

服务器支持通过多种身份验证方法 AUTH_METHOD 环境变量。选择适合您的平台和场景的方法：

默认值（Azure CLI）： 使用 DefaultAzureCredential Azure Identity SDK的链。在开发人员计算机上，这会从以下位置获取凭据 az login无需额外配置。这是原始行为，在Windows上效果最佳，Claude Desktop可以访问Azure CLI令牌缓存。

设备代码： 在第一个API调用中，将URL和一次性代码打印到stderr。您可以在任何浏览器中打开URL，输入代码，然后使用您的Azure帐户登录。令牌缓存在会话的内存中。这是推荐的方法 使用Claude Desktop的Mac用户，因为macOS上的Claude Desktop进程无法访问Azure CLI令牌缓存。

要使用设备代码流，您需要注册Azure应用程序 “允许公共客户端流” 启用：

1. 首选 Azure 门户 >应用程序注册>新注册
2. 命名它（例如“结构MCP”）并注册
3. 在...之下 认证 > 高级设置，set “允许公共客户端流” 到 是
4. 在...之下 API权限，添加 https://api.fabric.microsoft.com/Workspace.ReadWrite.All （或您的工具所需的范围）
5. 复制 应用程序（客户端）ID 和你的 目录（租户）ID

客户端密码： 使用具有客户端凭据的服务主体。需要使用客户端密码注册Azure应用程序。适用于CI/CD管道、自动化脚本或任何无法进行交互式登录的无头环境。

交互式浏览器： 打开OAuth登录的浏览器窗口。适用于服务器进程可以启动浏览器的系统。可选的 AZURE_CLIENT_ID 和 AZURE_TENANT_ID 可以针对特定的应用程序和租户提供。

工作区安全防护

通过控制哪些工作区允许写入操作（创建、更新、删除） WRITABLE_WORKSPACES 环境变量。只有与配置的名称模式匹配的工作空间才允许CUD（创建、更新、删除）操作。读取操作从不受限制。

默认行为：当 WRITABLE_WORKSPACES 如果未设置或为空，则阻止所有破坏性操作。 您必须显式配置此变量以启用写入。

设置逗号分隔的glob模式：

WRITABLE_WORKSPACES=*-Dev,*-Test,Sandbox*

通配符示例：

• * 匹配所有工作区（允许所有内容）
• *-Dev 匹配“销售开发”、“财务开发”
• Sandbox* 匹配“Sandbox-123”、“Sandbox Mike”
• Exact-Name 仅匹配“精确名称”（不区分大小写）

防护工具（共102个） --创建、更新或删除工作区项的每个工具：

无防护： 读取操作（列表、get、get_definition、get_bim、get_tmdl）、查询执行（DAX、KQL、SQL、GraphQL）、运行/刷新/取消操作、导出操作和部署管道CRUD（租户级别，非工作区范围）。

带防护的Claude桌面配置（Windows）：

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "@einlogic/mcp-fabric-api"],
      "env": {
        "WRITABLE_WORKSPACES": "*-Dev,*-Test,Sandbox*"
      }
    }
  }
}

带防护的Claude桌面配置（macOS）：

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "@einlogic/mcp-fabric-api"],
      "env": {
        "AUTH_METHOD": "device-code",
        "AZURE_CLIENT_ID": "your-app-client-id",
        "AZURE_TENANT_ID": "your-tenant-id",
        "WRITABLE_WORKSPACES": "*-Dev,*-Test,Sandbox*"
      }
    }
  }
}

带防护的Claude代码CLI：

WRITABLE_WORKSPACES="*-Dev,*-Test" claude mcp add fabric -- npx -y @einlogic/mcp-fabric-api

未配置时出错：

WRITABLE_WORKSPACES is not configured. Destructive actions are blocked by default. Set WRITABLE_WORKSPACES to a comma-separated list of workspace name patterns, or "*" to allow all.

工作区不在允许列表中时出错：

Workspace "Production-Analytics" is not in the writable workspaces list. Allowed patterns: *-Dev, *-Test, Sandbox*

调试日志记录

启用详细调试日志记录以诊断API错误、检查请求/响应详细信息并跟踪长时间运行的操作。所有日志输出都转到 stderr （在Claude Desktop的日志文件中可见，永远不会干扰stdout上的JSON-RPC）。

设置 LOG_LEVEL 环境变量 debug:

Claude桌面配置：

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": ["-y", "@einlogic/mcp-fabric-api"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

克劳德代码CLI：

LOG_LEVEL=debug claude mcp add fabric -- npx -y @einlogic/mcp-fabric-api

在调试级别记录的内容：

顺从： 调试日志从不捕获实际的数据内容——没有查询文本、没有查询结果、没有定义有效载荷、没有承载令牌。只记录结构元数据（URL、大小、计数、时间、错误详细信息）。

在Claude Desktop中查看日志：

• macOS： ~/Library/Logs/Claude/mcp-server-fabric.log
• 窗户： %APPDATA%\Claude\logs\mcp-server-fabric.log

您还可以实时跟踪日志：

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-fabric.log

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\logs\mcp-server-fabric.log" -Wait

这 x-ms-request-id 每个API错误记录的值是向Microsoft打开Fabric API问题支持案例时所需的关键标识符。

读与写工具注释

每个工具都声明MCP ToolAnnotations 因此MCP客户端在配置UI中呈现只读工具时可以将其与突变区分开来。这允许用户在单个切换中启用所有读取工具，同时要求明确批准写入。

所有219个工具都带有这些提示。工作区安全防护(WRITABLE_WORKSPACES)无论客户允许什么，它仍然独立适用。

基于文件的I/O

为了避免大量有效负载压倒MCP客户端，定义工具使用文件路径而不是内联内容。服务器在向结构发送定义时从磁盘读取文件，并在从结构检索定义时将文件写入磁盘。

输入工具 --服务器从指定路径读取定义文件并上传到结构：

输出工具 --服务器从结构中检索定义并将其写入磁盘：

TMDL目录结构示例：

/tmp/my-model/
  model.tmdl
  definition.pbism
  definition/
    tables/
      Sales.tmdl
      Product.tmdl
    relationships.tmdl

发展

git clone https://github.com/your-org/mcp-fabric-api.git
cd mcp-fabric-api
npm install
npm run build
npm start
npm run dev          # Watch mode
npm run inspect      # Launch MCP Inspector

工具（共219个）

身份验证（4个工具）

工作区（6个工具）

湖屋（14工具）

仓库（9个工具）

笔记本（12个工具）

管道（15个工具）

语义模型（15个工具）

报告（13个工具）

数据流Gen2（8个工具）

Eventhouse（7个工具）

事件流（7个工具）

反射/激活器（7个工具）

GraphQL API（7个工具）

SQL端点（4个工具）

变量库（7个工具）

Git集成（9个工具）

部署管道（12个工具）

镜像数据库（11个工具）

KQL数据库（7个工具）

ML模型（5个工具）

ML实验（5个工具）

复制作业（11个工具）

外部数据共享（4个工具）

环境（20个工具）

结构环境是笔记本电脑和Spark作业定义的可连接运行时单元，它们捆绑了运行时版本、Spark计算配置和一组库。工具涵盖了整个CRUD表面以及暂存/发布生命周期。

许可证

AGPL-3.0