内容
# Azure Storage MCP Server
一个 [模型上下文协议 (Model Context Protocol, MCP)](https://github.com/anthropics/mcp-specification) 服务器，提供对 Azure 存储账户信息的只读访问。该服务器允许您通过标准化协议检查存储账户、网络配置、安全设置和指标。
## 功能
- **🔐 多种身份验证方法**：支持 Azure CLI、托管身份、服务主体和默认 Azure 凭据
- **📊 全面的存储账户信息**：基本属性、安全设置、网络配置、Blob 服务属性
- **🌐 网络规则和私有端点**：详细的网络访问规则和私有端点配置
- **📈 指标和监控**：存储使用情况和性能指标
- **🔒 安全优先设计**：只读操作，具备适当的输入验证和错误处理
- **🏗️ 生产就绪**：结构化日志记录、全面的错误处理和监控能力
## 可用工具
1. **`list_storage_accounts`** - 列出订阅或资源组中的所有存储账户
2. **`get_storage_account_details`** - 获取特定存储账户的详细信息
3. **`get_network_rules`** - 检索网络访问规则和防火墙设置
4. **`get_private_endpoints`** - 列出私有终结点连接及其状态
5. **`get_storage_metrics`** - 获取基本的使用情况和性能指标
## 安装
### 先决条件
- Python 3.10 或更高版本
- 已安装并配置 Azure CLI (`az login`)
- 具有访问存储帐户的适当 Azure 权限
### 使用 UV（推荐）
```bash
```
# 如果尚未安装UV，请进行安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆代码库
git clone <repository-url>
cd azure-storage-mcp
# 安装依赖
uv sync --all-extras
# 运行开发环境设置
./scripts/dev.sh
```
### 使用 pip
```bash
```
# 克隆仓库
git clone <repository-url>
cd azure-storage-mcp
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # 在 Windows 上: venv\Scripts\activate
# 安装包
pip install -e .
## 快速开始
### 1. 身份验证设置
服务器支持多种身份验证方法：
```bash
```
# Azure CLI（推荐用于开发）
az login
# 或者为服务主体设置环境变量
export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_AUTH_METHOD="service_principal"
```
### 2. 运行演示
```bash
```
# 运行交互式演示
uv run python scripts/demo.py
# 或者使用特定的订阅
uv run python scripts/demo.py "your-subscription-id"
```
### 3. 启动 MCP Server
```bash
```
# 启动MCP服务器
uv run azure-storage-mcp
# 或直接运行
uv run python -m azure_storage_mcp.server
```
## 在Windows上与Claude Desktop一起使用
本节提供了使用您的个人Azure凭据配置Azure Storage MCP服务器以与Windows上的Claude Desktop配合工作的逐步说明。
### 前提条件
- 从 [Claude.ai](https://claude.ai/download) 安装的 **Claude Desktop for Windows**
- 从 [Microsoft Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-windows) 安装的 **Azure CLI**
- **Windows PowerShell** 或 **命令提示符**
- 具有存储帐户的 **Azure 订阅** 以供检查
- **Docker Desktop**（可选，用于基于容器的设置）
### 选项 1：本地安装（推荐）
#### 步骤 1：安装先决条件
```powershell
# 安装 Azure CLI（如果尚未安装）
# 从以下地址下载: https://aka.ms/installazurecliwindows
# 安装 UV 包管理器
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 安装 Git（如果尚未安装）
# 从以下地址下载: https://git-scm.com/download/win
```
#### 步骤 2：克隆并设置 MCP Server
```powershell
```
# 克隆仓库
git clone https://github.com/your-username/azure-storage-mcp.git
cd azure-storage-mcp
# 安装依赖
uv sync --all-extras
# 测试安装
uv run python scripts/demo.py --help
```
#### 步骤 3：使用 Azure 进行身份验证
```powershell
# 使用个人账户登录 Azure
az login
# 验证您的登录并记录您的订阅 ID
az account show
# 可选：将特定订阅设置为默认
az account set --subscription "your-subscription-id"
# 使用MCP服务器测试身份验证
uv run python scripts/demo.py
```
#### 步骤 4：配置 Claude Desktop
创建或编辑 Claude Desktop 配置文件：
**位置**：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"azure-storage": {
"command": "uv",
"args": ["run", "azure-storage-mcp"],
"cwd": "C:\\path\\to\\your\\azure-storage-mcp",
"env": {
"AZURE_AUTH_METHOD": "default"
}
}
}
}
```
**替换** `C:\\path\\to\\your\\azure-storage-mcp` 为您克隆的仓库的实际路径。
#### 步骤 5：重启 Claude Desktop
1. 完全关闭 Claude Desktop
2. 重启 Claude Desktop
3. 打开一个新的对话
4. 现在应该可以使用 Azure Storage MCP 工具了
### 选项 2：Docker/OCI 容器设置
#### 步骤 1：安装 Docker Desktop
1. 下载并安装 [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows/)
2. 启动 Docker Desktop 并确保它正在运行
#### 步骤 2：拉取预构建镜像
```powershell
```
# 拉取最新的 Azure Storage MCP 镜像
docker pull ghcr.io/derek-ashmore/azure-storage-mcp:latest
# 验证镜像
docker images | findstr azure-storage-mcp
```
#### 第3步：使用Azure进行身份验证
```powershell
```
# 使用个人账户登录 Azure
az login
# 获取用于容器的 Azure 凭据
az account show
# 获取服务主体详细信息（如果您有的话）
# 或者使用下面的交互式登录方法
```
#### 第4步：使用Azure凭据运行容器
**选项A：使用Azure CLI身份验证（推荐）**
```powershell
```
# 创建一个用于容器认证的包装脚本
@'
#!/bin/bash
# 如果需要，使用设备代码登录
if ! az account show > /dev/null 2>&1; then
echo "请先在您的主机上运行 'az login'"
exit 1
fi
# 运行 MCP 服务器
exec azure-storage-mcp "$@"
'@ | Out-File -FilePath azure-mcp-wrapper.sh -Encoding UTF8
# 使用挂载的 Azure CLI 配置运行容器
docker run -it --rm `
-v "$env:USERPROFILE\.azure:/root/.azure:ro" `
-v "$PWD/azure-mcp-wrapper.sh:/usr/local/bin/azure-mcp-wrapper.sh:ro" `
--entrypoint="/usr/local/bin/azure-mcp-wrapper.sh" `
ghcr.io/derek-ashmore/azure-storage-mcp:latest
```
**选项 B：使用环境变量（服务主体）**
```powershell
# 设置您的 Azure 服务主体凭据
$env:AZURE_TENANT_ID = "your-tenant-id"
$env:AZURE_CLIENT_ID = "your-client-id"
$env:AZURE_CLIENT_SECRET = "your-client-secret"
$env:AZURE_SUBSCRIPTION_ID = "your-subscription-id"
# 测试容器
```bash
docker run --rm `
-e AZURE_TENANT_ID="$env:AZURE_TENANT_ID" `
-e AZURE_CLIENT_ID="$env:AZURE_CLIENT_ID" `
-e AZURE_CLIENT_SECRET="$env:AZURE_CLIENT_SECRET" `
-e AZURE_SUBSCRIPTION_ID="$env:AZURE_SUBSCRIPTION_ID" `
ghcr.io/derek-ashmore/azure-storage-mcp:latest `
uv run python scripts/demo.py "$env:AZURE_SUBSCRIPTION_ID"
```
#### 步骤 5：为容器配置 Claude Desktop
在 `%APPDATA%\Claude\claude_desktop_config.json` 创建配置文件：
```json
{
"mcpServers": {
"azure-storage": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "%USERPROFILE%\\.azure:/root/.azure:ro",
"-e", "AZURE_AUTH_METHOD=default",
"ghcr.io/derek-ashmore/azure-storage-mcp:latest"
],
"env": {}
}
}
}
```
对于服务主体身份验证，请使用：
```json
{
"mcpServers": {
"azure-storage": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "AZURE_TENANT_ID",
"-e", "AZURE_CLIENT_ID",
"-e", "AZURE_CLIENT_SECRET",
"-e", "AZURE_SUBSCRIPTION_ID",
"-e", "AZURE_AUTH_METHOD=service_principal",
"ghcr.io/derek-ashmore/azure-storage-mcp:latest"
],
"env": {
"AZURE_TENANT_ID": "your-tenant-id",
"AZURE_CLIENT_ID": "your-client-id",
"AZURE_CLIENT_SECRET": "your-client-secret",
"AZURE_SUBSCRIPTION_ID": "your-subscription-id"
}
}
}
}
```
### 测试集成
1. **在配置更改后重启 Claude Desktop**
2. **在 Claude 中打开一个新对话**
3. **使用示例查询测试集成：**
```
Can you list my Azure storage accounts?
Show me the network rules for my storage account named "mystorageaccount" in resource group "my-rg"
What are the current storage metrics for my storage account?
```
### Windows 安装故障排除
#### 常见问题
1. **"uv: command not found"**
```powershell
# 安装 UV 后重启 PowerShell
# 或手动安装：
Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy ByPass -File install.ps1
```
2. **"Azure CLI not found"**
```powershell
# 安装 Azure CLI
Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile AzureCLI.msi
Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'
```
3. **"Claude can't find the MCP server"**
- 验证 `claude_desktop_config.json` 中的路径使用双反斜杠 (`\\`)
- 确保路径存在并包含 MCP 服务器文件
- 检查 UV 和 Python 是否在你的 PATH 中
4. **"Authentication failed in container"**
```powershell
# 验证 Azure 登录
az account show
# 确保 Azure 配置目录正确挂载
# 路径应为：%USERPROFILE%\.azure:/root/.azure:ro
```
5. **"Permission denied" in Docker**
```powershell
# 确保 Docker Desktop 正在运行
# 检查 Docker 守护进程是否可访问
docker version
```
### 安全建议
1. **使用 Azure CLI 认证** 进行个人使用（最安全）
2. **限制服务主体权限** 仅限于所需的存储账户
3. **安全存储凭据** - 避免在配置文件中硬编码
4. **定期轮换凭据** 对于服务主体
5. **监控 Azure 中的访问日志** 以发现异常活动
### 性能提示
1. **本地安装**比容器在常规使用中更快
2. **容器方法**更适合隔离/测试环境
3. **在本地缓存 Docker 镜像**以避免重复下载
4. **在查询中使用特定的订阅 ID**以减少 API 调用
## 使用示例
### 列出存储账户
```json
{
"name": "list_storage_accounts",
"arguments": {
"subscription_id": "12345678-1234-1234-1234-123456789012",
"resource_group": "my-resource-group",
"include_deleted": false
}
}
```
### 获取存储账户详情
```json
{
"name": "get_storage_account_details",
"arguments": {
"subscription_id": "12345678-1234-1234-1234-123456789012",
"resource_group": "my-resource-group",
"account_name": "mystorageaccount",
"include_keys": false
}
}
```
### 获取网络规则
```json
{
"name": "get_network_rules",
"arguments": {
"subscription_id": "12345678-1234-1234-1234-123456789012",
"resource_group": "my-resource-group",
"account_name": "mystorageaccount"
}
}
```
### 获取存储指标
```json
{
"name": "get_storage_metrics",
"arguments": {
"subscription_id": "12345678-1234-1234-1234-123456789012",
"resource_group": "my-resource-group",
"account_name": "mystorageaccount",
"time_range": "24h",
"metrics": ["UsedCapacity", "Transactions"],
"aggregation_type": "Average"
}
}
```
## 配置
### 认证方法
设置 `AZURE_AUTH_METHOD` 环境变量以选择认证方式：
- `default` - DefaultAzureCredential（尝试多种方法）
- `cli` - Azure CLI 认证
- `managed_identity` - 托管身份
- `service_principal` - 使用环境变量的服务主体
### 环境变量
- `AZURE_AUTH_METHOD` - 认证方法（默认值："default"）
- `AZURE_TENANT_ID` - 服务主体认证的租户 ID
- `AZURE_CLIENT_ID` - 服务主体认证的客户端 ID
- `AZURE_CLIENT_SECRET` - 服务主体认证的客户端密钥
## 开发
### 项目结构
```
azure-storage-mcp/
├── src/azure_storage_mcp/
│ ├── __init__.py
│ ├── server.py # 主MCP服务器
│ ├── auth/ # 身份验证处理
│ ├── models/ # Pydantic数据模型
│ ├── tools/ # MCP工具实现
│ └── utils/ # 工具和异常
├── tests/ # 测试套件
├── scripts/ # 开发脚本
└── pyproject.toml # 项目配置
```
### 开发环境设置
```bash
```
# 克隆并设置开发环境
```bash
git clone <repository-url>
cd azure-storage-mcp
./scripts/dev.sh
```
### 运行测试
```bash
```
# 运行所有测试并生成覆盖率报告
./scripts/test.sh
# 或运行特定测试
uv run pytest tests/test_server.py -v
# 运行并生成覆盖率报告
uv run pytest --cov=src --cov-report=html
```
### 代码质量
```bash
```
# 格式化代码
uv run black src tests
# Lint 代码
uv run ruff check src tests
# 类型检查
uv run mypy src
```
## 所需的 Azure 权限
服务主体或用户需要以下权限：
- `Microsoft.Storage/storageAccounts/read`
- `Microsoft.Storage/storageAccounts/listKeys/action`（可选，用于 `include_keys`）
- `Microsoft.Storage/storageAccounts/blobServices/read`
- `Microsoft.Storage/storageAccounts/privateEndpointConnections/read`
- `Microsoft.Insights/metrics/read`（用于指标）
- `Microsoft.Insights/metricDefinitions/read`（用于指标）
## 响应格式
所有工具返回结构化的 JSON 响应，包含：
- **Data**: 以结构化格式返回的请求信息
- **Metadata**: 请求关联 ID、执行时间、时间戳
- **Summary**: 可读性强的结果摘要
示例响应结构：
```json
{
"storage_accounts": [...],
"total_count": 3,
"metadata": {
"timestamp": "2024-01-01T00:00:00Z",
"correlation_id": "12345678-1234-1234-1234-123456789012",
"execution_time_ms": 1250
},
"summary": "在订阅中找到 3 个存储帐户。按区域分布：eastus: 2, westus: 1"
}
```
## 错误处理
服务器提供了全面的错误处理，包含特定的错误类型：
- **AuthenticationError**: 与Azure认证相关的问题
- **PermissionError**: 请求操作的权限不足
- **ValidationError**: 输入参数无效
- **AzureAPIError**: 与Azure API相关的错误
- **AzureStorageMCPError**: 一般服务器错误
## 日志记录
服务器使用结构化日志记录，采用JSON格式以便于解析：
```json
{
"timestamp": "2024-01-01T00:00:00Z",
"tool_name": "list_storage_accounts",
"parameters": {...},
"success": true,
"execution_time_ms": 1250
}
```
## 安全考虑
- **只读操作**：所有操作都是只读且无破坏性的
- **输入验证**：所有输入都使用 Pydantic 模型进行验证
- **凭证安全**：凭证从不被记录或暴露
- **最小权限**：仅请求必要的权限
## CI/CD 工作流
该项目包括自动化测试工作流，用于验证 MCP server 在多个环境和部署方法中的功能。
### 可用工作流
1. **测试 MCP Server - Linux** (`.github/workflows/test-linux.yml`)
- 在最新的 Ubuntu 上运行
- 使用 Azure 认证测试 demo.py 脚本
- 在推送、拉取请求和手动调度时触发
2. **测试 MCP Server - Windows** (`.github/workflows/test-windows.yml`)
- 在最新的 Windows 上运行
- 使用 Azure 认证测试 demo.py 脚本
- 在推送、拉取请求和手动调度时触发
3. **构建和发布 OCI 镜像** (`.github/workflows/build-container.yml`)
- 使用 Podman 构建 OCI 容器镜像
- 测试容器化的 MCP 服务器与 Azure 认证
- 发布到 GitHub 容器注册表 (ghcr.io)
- 仅在主分支上发布（跳过拉取请求）
- 在推送、拉取请求和手动调度时触发
### 所需的机密
这两个工作流都需要配置以下 GitHub 机密：
- `AZURE_TENANT_ID` - 您的 Azure 租户 ID
- `AZURE_CLIENT_ID` - 服务主体客户端 ID
- `AZURE_CLIENT_SECRET` - 服务主体客户端机密
- `AZURE_SUBSCRIPTION_ID` - 目标 Azure 订阅 ID
### 工作流功能
- **跨平台测试**：确保在Linux和Windows上的兼容性
- **服务主体认证**：使用Azure服务主体进行CI/CD
- **错误捕获**：自动将失败日志作为工件上传
- **演示验证**：运行完整的demo.py脚本以验证所有MCP工具
### 手动触发
您可以通过 GitHub Actions 选项卡使用 workflow_dispatch 手动触发工作流。
## 故障排除
### 常见问题
1. **认证错误**
```bash
# 检查 Azure CLI 登录状态
az account show
# 如有需要，重新登录
az login
```
2. **权限错误**
```bash
# 检查您的权限
az role assignment list --assignee $(az account show --query user.name -o tsv)
```
3. **找不到订阅**
```bash
# 列出可用的订阅
az account list --query "[].{Name:name, Id:id}" --output table
```
### 调试模式
通过设置以下内容启用调试日志记录：
```bash
export AZURE_STORAGE_MCP_DEBUG=true
```
## 贡献
1. Fork 该仓库
2. 创建一个功能分支
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交一个拉取请求
## 许可证
本项目采用 MIT 许可证 - 详细信息请参见 LICENSE 文件。
## 支持
对于问题和疑问：
1. 检查 [故障排除部分](#troubleshooting)
2. 查看 [Azure Storage 文档](https://docs.microsoft.com/en-us/azure/storage/)
3. 在代码库中提交一个问题
## 致谢
- 基于 [Model Context Protocol (MCP)](https://github.com/anthropics/mcp-specification) 构建
- 由 [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python) 提供支持
- 使用 [UV](https://astral.sh/uv) 进行包管理
连接信息
猜你喜欢
暂无推荐服务器