Azure Synapse MCP服务器
用于Azure Synapse Analytics工作区管理的全面模型上下文协议（MCP）服务器。此服务器使AI代理能够通过标准化协议与Azure Synapse工作区交互，提供管道管理、工件开发、监控和调试功能。
特性
🚀 管道管理
- 创建、更新、删除管道：Synapse管道的全生命周期管理
- 运行管道：使用自定义参数执行管道
- 管道监测：实时监控管道执行状态
- 调试运行：支持通过详细的日志记录调试管道运行
📝 工件管理
- 笔记本：创建、更新、删除和管理Synapse笔记本
- SQL脚本：管理SQL脚本和存储过程
- 数据集：配置和管理数据集定义
- 链接服务：处理与外部数据源的连接
- 数据流：管理数据转换流
📊 监控与调试
- 管道运行监控：跟踪管道执行状态和性能
- 活动运行详细信息：监控管道内的单个活动执行情况
- 触发器监控：监控计划触发和基于事件的触发
- 误差分析：详细的错误报告和故障排除功能
🏢 工作区操作
- 游泳池管理：管理Spark池和SQL池
- 集成运行时：监控和管理集成运行时
- 访问控制：查看和管理工作区权限
- 资源监控：跟踪工作区资源使用情况
安装
先决条件
- Node.js 18.0.0或更高版本
- Azure Synapse分析工作区
- 具有适当权限的Azure服务主体
设置
- 克隆存储库:
git clone https://github.com/yourusername/azure-synapse-mcp-server.git
cd azure-synapse-mcp-server- 安装依赖项:
npm install- 配置环境:
cp .env.example .env
# Edit .env with your Azure Synapse configuration- 构建项目:
npm run build配置
环境变量
创建一个 .env 具有以下配置的文件：
# Azure Authentication
AZURE_TENANT_ID=your-tenant-id-here
AZURE_CLIENT_ID=your-client-id-here
AZURE_CLIENT_SECRET=your-client-secret-here
# Azure Synapse Workspace
SYNAPSE_WORKSPACE_NAME=your-workspace-name
SYNAPSE_WORKSPACE_URL=https://your-workspace-name.dev.azuresynapse.net
AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_RESOURCE_GROUP=your-resource-group
# MCP Server Configuration
MCP_SERVER_NAME=azure-synapse-mcp-server
MCP_SERVER_VERSION=1.0.0
LOG_LEVEL=infoAzure服务主体设置
- 创建服务主体:
az ad sp create-for-rbac --name "synapse-mcp-server" --role "Contributor" --scopes "/subscriptions/{subscription-id}/resourceGroups/{resource-group}"- 分配Synapse权限:
- 导航到Azure门户中的Synapse工作区 - 转到访问控制（IAM） - 添加角色分配：“Synapse参与者”或“Synapse管理员”
用法
运行服务器
地方发展:
npm run dev生产:
npm start与MCP检查员一起 （用于测试）：
npm run inspectorClaude桌面集成
将服务器添加到Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"azure-synapse": {
"command": "node",
"args": ["/path/to/azure-synapse-mcp-server/dist/index.js"],
"env": {
"AZURE_TENANT_ID": "your-tenant-id",
"AZURE_CLIENT_ID": "your-client-id",
"AZURE_CLIENT_SECRET": "your-client-secret",
"SYNAPSE_WORKSPACE_NAME": "your-workspace-name",
"SYNAPSE_WORKSPACE_URL": "https://your-workspace-name.dev.azuresynapse.net",
"AZURE_SUBSCRIPTION_ID": "your-subscription-id",
"AZURE_RESOURCE_GROUP": "your-resource-group"
}
}
}
}可用工具
管道作业
create_pipeline-创建新管道update_pipeline-更新现有管道delete_pipeline-删除管道get_pipeline-检索管道定义list_pipelines-列出工作区中的所有管道run_pipeline-执行管道get_pipeline_run-获取管道运行详细信息list_pipeline_runs-列出管道执行历史记录cancel_pipeline_run-取消正在运行的管道
工件管理
create_notebook-创建新笔记本update_notebook-更新笔记本内容delete_notebook-删除笔记本get_notebook-检索笔记本定义list_notebooks-列出所有笔记本create_sql_script-创建SQL脚本update_sql_script-更新SQL脚本内容delete_sql_script-删除SQL脚本get_sql_script-检索SQL脚本list_sql_scripts-列出所有SQL脚本create_dataset-创建数据集定义update_dataset-更新数据集配置delete_dataset-删除数据集get_dataset-检索数据集定义list_datasets-列出所有数据集create_linked_service-创建链接服务update_linked_service-更新链接服务配置delete_linked_service-删除链接的服务get_linked_service-检索链接的服务定义list_linked_services-列出所有链接的服务
监视工具
get_activity_runs-获取管道的活动运行详细信息get_trigger_runs-监控触发器执行情况list_active_pipeline_runs-列出当前正在运行的管道get_pipeline_metrics-获取管道性能指标get_workspace_status-获取整体工作区运行状况
工作空间管理
list_spark_pools-列出Spark池get_spark_pool-获取Spark池详细信息list_sql_pools-列出SQL池get_sql_pool-获取SQL池详细信息list_integration_runtimes-列出集成运行时get_integration_runtime-获取集成运行时详细信息
示例用法
创建和运行管道
// Ask Claude in Desktop:
"Create a simple copy pipeline in Azure Synapse that copies data from a blob storage source to a SQL sink, then run it"
// The MCP server will:
// 1. Use create_pipeline to define the pipeline
// 2. Use run_pipeline to execute it
// 3. Use get_pipeline_run to monitor progress监控管道执行
// Ask Claude:
"Show me the status of all running pipelines and any failed runs from the last 24 hours"
// The MCP server will:
// 1. Use list_active_pipeline_runs to get current executions
// 2. Use list_pipeline_runs with filters for failed runs
// 3. Use get_activity_runs for detailed failure analysis管理笔记本
// Ask Claude:
"Create a new Synapse notebook for data exploration with sample Spark code for reading from a data lake"
// The MCP server will:
// 1. Use create_notebook to create the notebook
// 2. Include sample PySpark code for data lake access发展
项目结构
src/
├── index.ts # Entry point
├── server.ts # Main MCP server setup
├── config/
│ └── config.ts # Configuration management
├── handlers/
│ ├── pipeline.handler.ts # Pipeline operation handlers
│ ├── artifact.handler.ts # Artifact operation handlers
│ ├── monitoring.handler.ts # Monitoring handlers
│ └── workspace.handler.ts # Workspace management handlers
├── services/
│ ├── azure-auth.service.ts # Azure authentication
│ ├── pipeline.service.ts # Pipeline API calls
│ ├── artifact.service.ts # Artifact API calls
│ ├── monitoring.service.ts # Monitoring API calls
│ └── workspace.service.ts # Workspace API calls
├── types/
│ ├── index.ts # Exported types
│ └── synapse.types.ts # Azure Synapse type definitions
└── utils/
├── logger.ts # Logging utility
└── error-handler.ts # Error handling utility可用脚本
npm run build-构建TypeScript项目npm run watch-观察变化并重建npm run start-启动MCP服务器npm run dev-构建并启动开发模式npm run inspector-从MCP检验员开始测试npm run lint-运行ESLintnpm run lint:fix-修复ESLint问题npm run test-运行测试npm run clean-清理构建工件
添加新工具
- 在相应的处理程序中定义工具模式
- 在相应的服务中实现工具逻辑
- 添加适当的错误处理和日志记录
- 使用工具文档更新此README
认证
支持的身份验证方法
- 服务主体 （推荐用于生产）
- 管理身份 （适用于Azure托管场景）
- Azure命令行界面 （用于发展）
必需的权限
服务主体需要以下权限：
Azure RBAC：
Contributor或Reader论资源群体Storage Blob Data Contributor（如果访问存储）
Synapse RBAC：
Synapse Contributor或Synapse AdministratorSynapse Artifact Publisher（用于创建/更新工件）Synapse Artifact User（用于读取工件）
故障排除
常见问题
- 认证失败
- 验证服务主体凭据 - 检查Azure AD令牌过期情况 - 确保正确的RBAC分配
- 管道运行失败
- 使用检查活动运行详细信息 get_activity_runs - 验证链接的服务连接 - 查看集成运行时状态
- 未找到工件
- 验证工件名称拼写 - 检查工作区权限 - 确保工件存在于指定的工作区中
调试模式
通过设置启用详细日志记录 DEBUG_MODE=true 在你的 .env 文件。
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 运行linting和测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持
对于问题和疑问：
- 在GitHub存储库中创建问题
- 检查故障排除部分
- 查看Azure Synapse文档