MCP Azure Cloudshell

MCP Azure云外壳

模型上下文协议（MCP）服务器，使开发人员能够在Azure Cloud Shell环境中执行Azure CLI命令和bash脚本。

快速链接

• 特性 -可用工具和功能
• 安装 -通过3个步骤开始
• 用法 -Stdio与HTTP传输设置
• 后续步骤 -生产部署和开发建议
• 运作原理 -通过代码引用进行技术深度挖掘
• 成本和账单 -定价明细和创建的资源
• 故障排除 -常见问题和解决方案

特性

此MCP服务器通过以下工具提供对Azure Cloud Shell的编程访问：

工具

1. azure_cli -执行Azure CLI命令

- 运行任何 az Azure环境中的命令 - 例子： az account show, az vm list, az group list

1. azure_shell -执行bashshell命令

- 运行常规bash命令、git操作或脚本 - 例子： ls -la, git status, pwd, cat file.txt

1. azure_shell_reconnect -强制重新连接到Cloud Shell

- 如果连接似乎过时或命令超时，请使用

运作原理

服务器使用官方Azure REST API连接到Azure云外壳：

1. 认证 -用途 DefaultAzureCredential 从 @azure/identity
2. 控制台配置 -通过Azure Management API提供云外壳控制台
3. 终端创建 -创建bash终端会话
4. WebSocket连接 -为命令执行建立双向通信

先决条件

在使用此服务器之前，您需要：

1. Azure帐户 具有活动订阅
2. Azure命令行界面 本地安装（用于身份验证设置）
3. Node.js 18+已安装
4. Azure云外壳 在您的订阅中注册的资源提供商

注册Azure Cloud Shell资源提供程序

如果这是您第一次使用Cloud Shell，请注册资源提供商：

az provider register --namespace Microsoft.CloudShell

身份验证设置

服务器使用 DefaultAzureCredential，支持多种身份验证方法。选择一个：

选项1:Azure CLI（建议用于开发）

az login

这是当地发展最简单的方法。服务器将自动使用您的Azure CLI凭据。

选项2：环境变量（服务主体）

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

选项3：托管身份（适用于Azure托管的应用程序）

如果在Azure虚拟机、应用服务或功能上运行，将自动使用托管身份。

安装

1. 导航到项目目录：

cd mcp-azure-cloudshell

1. 安装依赖项：

npm install

1. 构建服务器：

npm run build

用法

此服务器支持两种传输机制。选择最适合您的用例：

运输选项

选项1：标准运输（建议用于克劳德规范）

启动服务器：

npm start

使用CLI添加到Claude代码中：

claude mcp add --transport stdio azure-cloudshell -- node /path/to/mcp-azure-cloudshell/dist/index.js

或手动配置 在 .mcp.json （本地）或 ~/.config/claude/mcp.json （全球）：

{
  "mcpServers": {
    "azure-cloudshell": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-azure-cloudshell/dist/index.js"],
      "transport": "stdio"
    }
  }
}

选项2:HTTP传输（用于远程/Web访问）

启动HTTP服务器：

npm run start:http

服务器启动于 http://localhost:3000/mcp 默认情况下。使用 PORT=8080 定制。

在Claude代码中配置 (.mcp.json):

{
  "mcpServers": {
    "azure-cloudshell-http": {
      "url": "http://localhost:3000/mcp",
      "transport": "http"
    }
  }
}

卷曲测试：

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl-client", "version": "1.0.0"}}, "id": 1}'

# List tools (use session ID from response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: YOUR-SESSION-ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": 2}'

有关详细的HTTP设置、部署选项和故障排除，请参阅 HTTP传输.md.

查询示例

添加服务器后，您可以向Claude Code提出以下问题：

• “我使用的是什么Azure订阅？”
• “列出我的所有资源组”
• “显示eastus区域中的所有虚拟机”
• “在westus2中创建一个名为test-rg的新资源组”
• “我在Cloud Shell中的当前目录是什么？”
• “克隆存储库https://github.com/example/repo云壳”

后续步骤

现在您已经设置好了服务器，以下是一些建议的后续步骤：

用于生产部署（HTTP传输）

1. 添加身份验证：实现承载令牌或API密钥验证

   app.use((req, res, next) => {
     const authHeader = req.headers.authorization;
     if (!authHeader || !validateToken(authHeader)) {
       return res.status(401).json({ error: 'Unauthorized' });
     }
     next();
   });

1. 启用HTTPS：使用有效的TLS证书进行安全通信

- 在反向代理（nginx、Caddy）后面部署 - 使用Let's Encrypt获取免费证书 - 配置HTTPS重定向

1. 部署到云端:

- Azure应用服务: az webapp up --name my-mcp-server --resource-group my-rg - AWS Lambda：将AWS Lambda Web适配器与HTTP服务器一起使用 - 码头工人：构建和部署容器化版本（参见 HTTP传输.md)

1. 添加监控：跟踪使用情况、错误和性能

- 应用洞察（Azure） - 云观察（AWS） - 自定义日志记录和指标

1. 实施速率限制：通过请求限制防止滥用

   npm install express-rate-limit

为了发展

1. 使用Azure凭据进行测试：确保 az login 已配置并测试实际命令执行
2. 添加自定义工具：使用其他Azure特定工具扩展服务器
3. 改进输出解析：增强 cleanOutput 更好的命令结果格式化方法
4. 添加PowerShell支持：修改终端创建以支持PowerShell和bash

了解更多信息

• 阅读 HTTP传输.md 有关详细的HTTP设置和部署指南
• 探索 Azure云外壳REST API 文档
• 看看 模型上下文协议规范

项目结构

mcp-azure-cloudshell/
├── src/
│   ├── index.ts          # Main MCP server (stdio transport)
│   ├── http-server.ts    # HTTP server (HTTP transport)
│   └── cloudshell.ts     # Azure Cloud Shell connection manager
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── README.md             # This file
└── HTTP-TRANSPORT.md     # HTTP transport documentation

发展

发展模式

在监视模式下运行TypeScript编译器：

npm run dev

构建

npm run build

启动服务器（用于测试）

npm start

建筑细部

引擎盖下的工作原理

MCP服务器通过三个步骤建立与Azure Cloud Shell的连接：

步骤1：控制台配置（cloudshell.ts:60-93）

PUT https://management.azure.com/providers/Microsoft.Portal/consoles/default

• 呼叫 微软。门户 资源提供程序（不是Microsoft.CloudShell！）
• 创建或检索现有的Cloud Shell控制台元数据对象
• 这是一个 自由 无需计算/存储成本的管理资源
• 返回指向Cloud Shell网关的URI

步骤2：终端创建（cloudshell.ts:98-133）

POST https://{gateway-url}/terminals?cols=160&rows=40&shell=bash

• 在Cloud Shell环境中创建bash终端会话
• 指定端子尺寸和外壳类型
• 返回用于双向通信的WebSocket URI和终端ID

步骤3:WebSocket连接（cloudshell.ts:138-177）

wss://{gateway-url}/terminals/{terminal-id}

• 打开与终端的持久WebSocket连接
• 所有命令输入/输出都通过此连接
• 命令被排队，输出被缓冲，直到完成
• 通过观察shell提示（$、#、>）来检测命令完成

命令执行流程（cloudshell.ts:212-244）

1. 通过WebSocket发送带有换行符的命令(command\n)
2. 消息到达时缓冲区中累积的输出
3. 出现提示字符时检测到完成
4. ANSI转义码已删除，输出已清理
5. 命令行回声和最终提示从结果中删除

身份验证流程

┌─────────────────┐
│ DefaultAzure    │
│ Credential      │
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Azure           │
│ Management API  │
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Cloud Shell     │
│ Console         │
└────────┬────────┘
         │
         v
┌─────────────────┐
│ Terminal        │
│ Session         │
└────────┬────────┘
         │
         v
┌─────────────────┐
│ WebSocket       │
│ Connection      │
└─────────────────┘

使用的API端点

1. 控制台配置

- PUT https://management.azure.com/providers/Microsoft.Portal/consoles/default?api-version=2020-04-01-preview - 退货： { properties: { uri: "https://...", provisioningState: "Succeeded", osType: "linux" } }

1. 终端创建

- POST https://{gateway-url}/terminals?cols=160&rows=40&shell=bash - 退货： { id: "terminal-id", socketUri: "wss://..." }

1. WebSocket连接

- wss://{gateway-url}/terminals/{terminal-id} - 协议：具有终端I/O的双向文本消息

代码架构

index.ts（MCP服务器）

import { AzureCloudShell } from "./cloudshell.js";

// Server maintains a singleton Cloud Shell instance
let cloudShell: AzureCloudShell | null = null;

// On first tool call, initialize connection
if (!cloudShell) {
  cloudShell = new AzureCloudShell(credential);
  await cloudShell.connect(); // Runs 3-step connection process
}

// Execute commands through the established connection
const result = await cloudShell.executeCommand(command, timeout);

这 .js 需要在导入中进行扩展，因为：

• TypeScript编译为ES模块("type": "module" 在package.json中）
• ES模块导入必须包含文件扩展名
• 在运行时，Node.js加载 dist/cloudshell.js （编译输出）

cloudshell.ts（连接管理器）

export class AzureCloudShell {
  private ws: WebSocket | null = null;           // WebSocket connection
  private commandQueue: Array = [];       // Queue for sequential commands
  private outputBuffer: string = "";             // Accumulates command output
  private isReady: boolean = false;              // Connection state

  async connect() {
    await this.provisionConsole();   // Step 1: Get console URI
    await this.createTerminal();     // Step 2: Create terminal
    await this.connectWebSocket();   // Step 3: Open WebSocket
  }

  async executeCommand(command: string, timeout: number): Promise {
    // Send command via WebSocket
    this.ws.send(`${command}\n`);

    // Wait for completion (detected by prompt characters)
    return new Promise((resolve, reject) => {
      this.commandQueue.push({ command, resolve, reject, timeout });
    });
  }

  private handleMessage(data: WebSocket.Data) {
    // Accumulate output until prompt detected
    this.outputBuffer += data.toString();

    // Resolve pending command when prompt appears
    if (message includes prompt characters) {
      currentCommand.resolve(this.cleanOutput(this.outputBuffer));
    }
  }
}

关键设计模式：

• Singleton连接：每个服务器实例一个WebSocket
• 指令队列：顺序执行可防止输出交错
• 基于承诺的API：为调用者清理async/await接口
• 自动清理：SIGINT/SIGTERM处理程序正常断开连接

命令执行

服务器通过以下功能处理命令执行：

• 超时支持 -每个命令可配置超时（默认30秒）
• 输出清洁 -删除ANSI转义码和端子提示
• 队列管理 -按顺序处理多个命令
• 错误处理 -为故障提供清晰的错误消息

故障排除

身份验证错误

错误： “获取访问令牌失败”

解决：

• 确保您已使用Azure CLI登录： az login
• 如果使用环境变量，请验证您的服务主体凭据
• 检查您在Azure订阅中是否具有适当的权限

连接错误

错误： “配置控制台失败”

解决：

• 确保Microsoft。CloudShell资源提供程序已注册
• 验证您的订阅是否处于活动状态
• 检查与Azure的网络连接

命令超时

错误： “命令在30000毫秒后超时”

解决：

• 增加命令中的超时参数
• 检查命令是否实际长时间运行
• 使用 azure_shell_reconnect 刷新连接的工具

WebSocket错误

错误： “WebSocket连接已关闭”

解决：

• Cloud Shell会话在20分钟不活动后超时
• 使用 azure_shell_reconnect 建立新连接
• 服务器将在下一个命令时自动重新连接

成本和账单

创建了哪些资源？

此MCP服务器 非 创建虚拟机、沙盒或资源组。它使用REST API连接到Azure现有的Cloud Shell基础架构。

使用的资源提供者

微软。门户资源提供者

• 资源类型: Microsoft.Portal/consoles
• 成本: 自由 -只需跟踪Cloud Shell会话的元数据
• 它的作用：创建引用Cloud Shell网关的控制台对象
• 位置：仅管理平面，没有计算/存储资源

微软。CloudShell资源提供程序

• 资源类型：仅限注册(operations)
• 成本: 自由 -仅API操作定义
• 它的作用：在订阅中启用Cloud Shell API

Cloud Shell实际提供了什么（仅限首次使用）

当你第一次使用Cloud Shell时，Azure会自动配置：

1.存储账户（~0.05-0.10/月）

• 资源：Azure文件共享（5 GB）
• 目的：为您的 $HOME 目录
• 命名：通常 cs
• 成本：标准LRS存储约0.05-0.10美元/月
• 生命周期：创建一次，跨会话持久

2.容器实例（大部分免费）

• 资源：shell会话的临时Linux容器
• 成本:

- 前20小时/月: 自由 - 20小时后：约0.0013美元/秒（连续运行约4.68美元/小时）

• 生命周期:

- 在第一个命令下旋转 - 20分钟不活动后自动终止 - 不运行时不收费

3.网络出口（限额内免费）

• 资源：WebSocket流量和Azure API调用
• 成本：通常由Azure免费层覆盖
• 体积：最小（仅命令I/O）

成本比较

重要说明

• 此服务器使用 相同 您通过portal.azure.com访问的Cloud Shell环境
• 除了标准Cloud Shell之外，不会创建其他资源
• 20分钟的空闲超时可防止成本失控
• 存储成本持续存在，但很低
• 每月前20小时的计算完全免费

监控成本

要检查订阅中是否存在Cloud Shell存储，请执行以下操作：

az storage account list --query "[?tags.ms-resource-usage=='azure-cloud-shell']"

要查看您的Cloud Shell使用情况：

• Azure门户→ 成本管理→ 成本分析
• 按服务筛选：“Azure容器实例”和“存储”

局限性

1. 会话超时 -Cloud Shell会话在20分钟不活动后超时
2. 单会话 -每个服务器实例只有一个活动会话
3. 输出解析 -复杂的交互式命令可能无法完美工作
4. 速率限制 -适用Azure API费率限制
5. 免费等级限制 -每月20小时免费计算；按标准费率计费的额外小时数

安全注意事项

1. 凭证安全 -使用Azure的官方证书链
2. 无凭据存储 -代币按需提取
3. API范围 -仅限于Azure Management API范围
4. 命令执行 -命令在您的Cloud Shell环境中以您的权限运行

高级用法

自定义超时

// In Claude Code, specify longer timeout for slow commands
"List all resources with a 60 second timeout using azure_cli with command 'az resource list' and timeout 60"

链接命令

# Use && to chain multiple commands
"Execute in azure_shell: cd /home && ls -la && pwd"

文件操作

# Create and read files in Cloud Shell
"Create a file in Cloud Shell named test.txt with content 'Hello World'"
"Read the contents of test.txt in Cloud Shell"

api参考

azure_cli工具

参数：

• command （字符串，必填）-要执行的Azure CLI命令
• timeout （数字，可选）-超时秒数（默认值：30）

退货：

• 命令输出为文本

azure_shell工具

参数：

• command （string，必填）-要执行的Bash命令
• timeout （数字，可选）-超时秒数（默认值：30）

退货：

• 命令输出为文本

azure_shell_reconnect工具

参数：

• 无

退货：

• 成功消息

贡献

要扩展此服务器，请执行以下操作：

1. 添加新工具 -在中定义其他工具 src/index.ts
2. 增强输出解析 -改善 cleanOutput 方法in src/cloudshell.ts
3. 添加PowerShell支持 -修改终端创建以使用 pwsh 而不是 bash
4. 实施资源 -将Azure资源作为MCP资源公开

资源

• Azure云外壳文档
• Azure身份SDK
• 模型上下文协议
• 克劳德代码MCP指南

许可证

麻省理工学院

致谢

此服务器是使用以下方式构建的：

• @azure/identity -Azure身份验证
• @modelcontextprotocol/sdk -MCP服务器框架
• ws -WebSocket客户端
• Azure云外壳REST API