convez.ai
MCP ServerDevOps & InfraestruturaAvançado
Arasefe

Azure MCP Server

Arasefe/azure-mcp-server

Integra Azure/M365 ao Claude Code via protocolo MCP com 47 tools prontas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP (Model Context Protocol) que expõe operações de gerenciamento do Azure e Microsoft 365 como ferramentas invocáveis pelo Claude Code. Suporta autenticação com Service Principal via certificado e integra Intune, Defender for Cloud, Sentinel, Purview e Entra ID através de 47 tools pré-configuradas.

Instalação

$npx convez-ai Arasefe/azure-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciar recursos, usuários e RBAC no Azure programaticamente
  • Automatizar provisionamento em massa no Intune e Microsoft 365
  • Consultar alertas de segurança do Defender for Cloud e Sentinel
  • Executar operações de conformidade e auditoria via Purview
  • Invocar operações de infraestrutura durante conversas no Claude

Veredito

Ferramenta robusta para quem já tem familiaridade com Azure, Graph API e certificados de Service Principal. Excelente para automação de infraestrutura e gerenciamento em escala, mas exige setup complexo de autenticação e permissões. Não é plug-and-play.

README

A tradução para o português deste README ainda está na fila.

Azure MCP Server

A local Model Context Protocol (MCP) stdio server that exposes Azure and Microsoft 365 management operations as tools Claude Code can invoke directly during a conversation.

Table of Contents

  1. What is an MCP Server?
  2. Architecture Overview
  3. Prerequisites
  4. Project Setup
  5. Authentication — Service Principal with Certificate
  6. Environment Configuration
  7. Server Structure
  8. Integrated Services
  9. Required Permissions Summary
  10. Integrating with Claude Code
  11. Testing the Server
  12. Troubleshooting
  13. Bulk User Provisioning

1. What is an MCP Server?

Model Context Protocol (MCP) is an open standard that allows AI models like Claude to securely interact with external tools, APIs, and data sources. An MCP server exposes capabilities (tools) that Claude can invoke during a conversation.

This server is a Node.js MCP stdio server that:

  • Speaks JSON-RPC 2.0 over stdin/stdout — Claude Code spawns it as a subprocess
  • Authenticates to Azure/Microsoft 365 using a Service Principal with certificate-based auth
  • Registers all 47 tools inline in server.js so Claude Code can discover and invoke them
  • Requires no running port or separate process — Claude Code manages the lifecycle

2. Architecture Overview

Claude Code (AI)
      │
      │  spawns process, communicates via stdio (JSON-RPC 2.0)
      ▼
server.js  (MCP stdio server — node server.js)
      │
      ├── Graph API (graph.microsoft.com)  ──── Intune, Purview, Entra ID
      ├── ARM API (management.azure.com)   ──── Defender, Sentinel, Resources
      └── Azure CLI (exec)                 ──── RBAC, legacy operations

Authentication flow:

server.js
   └── ClientCertificateCredential (cavalry-sp.combined.pem)
         ├── getGraphToken()  →  https://graph.microsoft.com/.default
         └── getARMToken()    →  https://management.azure.com/.default

3. Prerequisites

RequirementDetails
Node.jsv18 or later
Azure CLIInstalled and authenticated (az login)
Azure SubscriptionActive subscription
Microsoft 365 TenantWith E3/E5 licensing for Purview features
Service PrincipalWith certificate-based authentication
Claude CodeInstalled (npm install -g @anthropic-ai/claude-code)

4. Project Setup

4.1 Install dependencies

cd azure-mcp-server
npm install

4.2 Project structure

azure-mcp-server/
├── server.js                  # MCP stdio server — all 47 tools registered here
├── mcp-client.js              # Thin client library used by chat.js
├── chat.js                    # Interactive CLI for manual tool testing
├── provision-users.js         # One-shot bulk user provisioning script (20 users)
├── .env                       # Environment variables (never commit this)
├── .gitignore                 # Must include .env and *.pem
├── cavalry-sp.combined.pem    # Service principal certificate (never commit)
└── package.json

4.3 .gitignore

.env
*.pem
node_modules/

5. Authentication — Service Principal with Certificate

The server uses certificate-based Service Principal authentication — the most secure option for automated workloads.

5.1 Create the Service Principal

# Create the SP and generate a self-signed certificate
az ad sp create-for-rbac \
  --name "cavalry-sp" \
  --create-cert \
  --cert cavalry-sp-cert \
  --keyvault <your-keyvault-name>

Or with a local certificate:

# Generate certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout cavalry-sp.key \
  -out cavalry-sp.crt \
  -subj "/CN=cavalry-sp"

# Combine into PEM (required by @azure/identity)
cat cavalry-sp.crt cavalry-sp.key > cavalry-sp.combined.pem

# Upload public cert to the app registration
az ad app credential reset \
  --id <CLIENT_ID> \
  --cert @cavalry-sp.crt

5.2 Find your credentials

# Tenant ID
az account show --query tenantId -o tsv

# Client ID (App ID of service principal)
az ad sp show --display-name "cavalry-sp" --query appId -o tsv

# Subscription ID
az account show --query id -o tsv

5.3 Authentication code in server.js

import { ClientCertificateCredential } from "@azure/identity";

const credential = new ClientCertificateCredential(
  process.env.AZURE_TENANT_ID,
  process.env.AZURE_CLIENT_ID,
  path.join(__dirname, "cavalry-sp.combined.pem"),
);

async function getGraphToken() {
  const r = await credential.getToken("https://graph.microsoft.com/.default");
  return r.token;
}

async function getARMToken() {
  const r = await credential.getToken("https://management.azure.com/.default");
  return r.token;
}

6. Environment Configuration

6.1 .env file

AZURE_CLIENT_ID="<your-service-principal-client-id>"
AZURE_TENANT_ID="<your-tenant-id>"
AZURE_SUBSCRIPTION_ID="<your-subscription-id>"
SENTINEL_RESOURCE_GROUP="<resource-group-containing-sentinel-workspace>"
SENTINEL_WORKSPACE_NAME="<log-analytics-workspace-name>"

# Required only for provision-users.js (uses client secret auth instead of certificate)
AZURE_CLIENT_SECRET="<your-client-secret>"

6.2 Find Sentinel workspace details

az resource list \
  --resource-type "Microsoft.OperationsManagement/solutions" \
  --query "[?contains(name,'SecurityInsights')].{name:name, resourceGroup:resourceGroup}" \
  -o table

7. Server Structure

7.1 Tool registration pattern

Each tool is declared in the tools array in server.js with a name, description, and JSON schema:

{
  name: "list_resource_groups",
  description: "List all Azure resource groups in the subscription",
  inputSchema: { type: "object", properties: {} }
}

7.2 Tool handler pattern

Each tool name is handled in the CallToolRequestSchema switch block:

case "list_resource_groups": {
  const groups = [];
  for await (const rg of resourceClient.resourceGroups.list()) groups.push(rg.name);
  result = { resourceGroups: groups };
  break;
}

Errors are returned as MCP error responses (not thrown), so Claude Code always gets a readable message.

7.3 Adding a new tool (checklist)

  1. Add an entry to the tools array in server.js
  2. Add a case block in the CallToolRequestSchema handler
  3. Grant the service principal the required permission
  4. Test with the MCP stdio test below
  5. Restart Claude Code (or run /mcp to reload)

8. Integrated Services

8.1 Azure Portal

Covers resource management, identity, RBAC, and Administrative Units.

API used: Azure Resource Manager SDK + Microsoft Graph API + Azure CLI

Tools:

Tool NameDescription
list_resource_groupsList all resource groups in the subscription
create_resource_groupCreate a new resource group (params: name, location)
delete_resource_groupDelete a resource group (params: name)
create_userCreate an Entra ID user (params: upn, displayName, password)
delete_userDelete an Entra ID user (params: upn)
list_usersList all Entra ID users via Azure CLI
list_graph_usersList users via Graph API with pagination
assign_roleAssign RBAC role (params: assignee, role, scope)
list_role_assignmentsList role assignments for a user (params: assignee)
list_ausList all Administrative Units
create_auCreate an Administrative Unit (params: displayName, description)
assign_au_roleAssign scoped role in AU (params: auId, upn, roleTemplateId)
add_au_memberAdd user to Administrative Unit (params: auId, upn)

Required permissions:

PermissionTypePurpose
User.ReadWrite.AllGraph ApplicationCreate/delete users
RoleManagement.ReadWrite.DirectoryGraph ApplicationAssign directory roles
AdministrativeUnit.ReadWrite.AllGraph ApplicationManage Administrative Units
ContributorAzure RBAC (Subscription)Manage resource groups

8.2 Microsoft Intune

API used: Microsoft Graph API v1.0 (/deviceManagement/...)

Tools:

Tool NameDescription
list_intune_devicesList all Intune-managed devices
list_noncompliant_devicesList devices with compliance state = noncompliant
sync_intune_deviceTrigger device sync (params: deviceId)
list_intune_compliance_policiesList all device compliance policies

Required permissions:

PermissionTypePurpose
DeviceManagementManagedDevices.Read.AllGraph ApplicationList/get managed devices
DeviceManagementManagedDevices.ReadWrite.AllGraph ApplicationTrigger device sync
DeviceManagementConfiguration.Read.AllGraph ApplicationList compliance policies

How to grant: Azure Portal → Entra ID → App registrations → your app → API permissions → Add a permission → Microsoft Graph → Application permissions → search, add, then Grant admin consent.


8.3 Microsoft Defender for Cloud

API used: Azure Resource Manager REST API (management.azure.com)

Token: getARMToken() — scope: https://management.azure.com/.default

Tools:

Tool NameDescription
list_defender_alertsList all Defender for Cloud security alerts
get_secure_scoreGet the subscription's secure score
list_defender_recommendationsList security recommendations/assessments
update_defender_alertUpdate alert status (params: alertName, resourceGroup, status)

Required permissions:

RoleScopePurpose
Security ReaderSubscriptionRead alerts, secure score, recommendations
Security AdminSubscriptionUpdate/dismiss alerts
az role assignment create \
  --assignee <CLIENT_ID> \
  --role "Security Reader" \
  --scope /subscriptions/<SUBSCRIPTION_ID>

8.4 Microsoft Sentinel

API used: Azure Resource Manager REST API + Log Analytics Query API

Prerequisites: Sentinel must be onboarded to a Log Analytics workspace. Verify with:

az resource list \
  --resource-type "Microsoft.OperationsManagement/solutions" \
  --query "[?contains(name,'SecurityInsights')].{name:name,resourceGroup:resourceGroup}" \
  -o table

Tools:

Tool NameDescription
list_sentinel_incidentsList all Sentinel incidents (ordered by creation time)
get_sentinel_incidentGet incident details (params: incidentId)
update_sentinel_incidentUpdate incident (params: incidentId, status, severity, classification, classificationComment)
list_sentinel_analytics_rulesList all analytics/detection rules
run_sentinel_kql_queryRun KQL query (params: query, timespan)

Required permissions:

RoleScopePurpose
Microsoft Sentinel ReaderResource GroupList incidents, rules
Microsoft Sentinel ResponderResource GroupUpdate incidents
Log Analytics ReaderResource GroupRun KQL queries
az role assignment create --assignee <CLIENT_ID> --role "Microsoft Sentinel Responder" \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG>
az role assignment create --assignee <CLIENT_ID> --role "Log Analytics Reader" \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG>

Environment variables required:

SENTINEL_RESOURCE_GROUP="your-resource-group"
SENTINEL_WORKSPACE_NAME="your-workspace-name"

8.5 Microsoft Purview M365

API used: Microsoft Graph API beta (/beta/...)

Token: getGraphToken() — scope: https://graph.microsoft.com/.default

Most Purview Graph endpoints are in /beta and require Microsoft 365 E3/E5 licensing.

8.5.1 Information Protection

Tool NameDescription
list_sensitivity_labelsList all configured sensitivity labels
get_sensitivity_labelGet label details (params: labelId)
list_sensitive_info_typesList sensitive info types (SSN, PHI, credit card, etc.)
list_label_policiesList sensitivity label policies

Required permissions: InformationProtectionPolicy.Read.All, SensitivityLabels.Read.All

8.5.2 Data Loss Prevention (DLP)

Tool NameDescription
list_dlp_policiesList DLP policies (beta endpoint)
list_dlp_alertsList DLP alerts via Security API

Required permissions: SecurityAlert.Read.All

DLP policy creation/modification requires Security & Compliance PowerShell — not available via Graph API.

8.5.3 Insider Risk Management (IRM)

Tool NameDescription
list_insider_risk_alertsList IRM alerts filtered by service source
list_insider_risk_policiesList IRM policies (beta endpoint)

Required permissions: SecurityAlert.Read.All

8.5.4 Information Barriers

Tool NameDescription
list_information_barrier_policiesList all Information Barrier policies
list_information_barrier_segmentsList all IB segments (user groups)

Required permissions: InformationBarrierPolicy.Read.All

8.5.5 eDiscovery

Tool NameDescription
list_ediscovery_casesList all eDiscovery cases
get_ediscovery_caseGet case details (params: caseId)
list_ediscovery_custodiansList custodians in a case (params: caseId)
list_ediscovery_holdsList legal holds in a case (params: caseId)

Required permissions: eDiscovery.Read.All

The service principal must also be added to the eDiscovery Manager role group in the Microsoft Purview compliance portal.

8.5.6 Records Management & Retention

Tool NameDescription
list_retention_labelsList all retention labels
list_retention_event_typesList retention event types for event-based retention

Required permissions: RecordsManagement.Read.All

8.5.7 Audit

Tool NameDescription
list_audit_logsList directory audit logs (params: filter, top)
list_signin_logsList sign-in audit logs (params: filter, top)

Example filter values:

  • activityDisplayName eq 'Add user'
  • initiatedBy/user/userPrincipalName eq 'admin@domain.com'

Required permissions: AuditLog.Read.All

Sign-in logs require Microsoft Entra ID P1 or P2 license.

8.5.8 Communication Compliance

Tool NameDescription
list_communication_compliance_policiesList Communication Compliance policies (beta)

Required permissions: CommunicationCompliance.Read.All

8.5.9 Compliance Manager

Tool NameDescription
list_compliance_assessmentsList Compliance Manager assessments (beta)

Required permissions: ComplianceManagement.Read.All

8.5.10 Data Security and Posture Management (DSPM)

Tool NameDescription
get_dspm_insightsGet sensitive data type summary and DSPM insights (beta)

Required permissions: InformationProtectionPolicy.Read.All


9. Required Permissions Summary

Azure RBAC (assign via CLI or Portal)

# Defender for Cloud
az role assignment create --assignee <CLIENT_ID> --role "Security Reader" \
  --scope /subscriptions/<SUBSCRIPTION_ID>

# Sentinel
az role assignment create --assignee <CLIENT_ID> --role "Microsoft Sentinel Responder" \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG>
az role assignment create --assignee <CLIENT_ID> --role "Log Analytics Reader" \
  --scope /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG>

Graph API Application Permissions (grant via Portal → Grant admin consent)

PermissionService
User.ReadWrite.AllAzure Portal — Users
RoleManagement.ReadWrite.DirectoryAzure Portal — RBAC
AdministrativeUnit.ReadWrite.AllAzure Portal — Administrative Units
DeviceManagementManagedDevices.Read.AllIntune — Devices
DeviceManagementManagedDevices.ReadWrite.AllIntune — Device sync
DeviceManagementConfiguration.Read.AllIntune — Compliance policies
SecurityAlert.Read.AllDefender, DLP, Insider Risk
InformationProtectionPolicy.Read.AllPurview — Sensitivity labels, DSPM
SensitivityLabels.Read.AllPurview — Sensitivity labels
InformationBarrierPolicy.Read.AllPurview — Information Barriers
eDiscovery.Read.AllPurview — eDiscovery
RecordsManagement.Read.AllPurview — Retention
AuditLog.Read.AllPurview — Audit logs
CommunicationCompliance.Read.AllPurview — Communication Compliance
ComplianceManagement.Read.AllPurview — Compliance Manager

10. Integrating with Claude Code

The server is registered in ~/.claude/settings.json. Claude Code spawns node server.js automatically — no manual startup needed.

{
  "mcpServers": {
    "azure": {
      "command": "node",
      "args": ["/Users/ismailyildirim/Desktop/azure-mcp-server/server.js"]
    }
  }
}

After changing settings.json, reload the server in Claude Code with /mcp or by restarting Claude Code.

In a conversation, ask:

"What Azure tools do you have available?"

Claude will list all 47 registered tools.


11. Testing the Server

MCP protocol smoke test (stdio)

Send the MCP handshake + a tools/list request directly over stdin:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | node server.js 2>/dev/null

You should see an initialize response followed by a tools/list response containing all 47 tools.

Test a live tool call

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_resource_groups","arguments":{}}}\n' \
  | node server.js 2>/dev/null

Test with a parameterised tool

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"run_sentinel_kql_query","arguments":{"query":"SecurityAlert | take 5","timespan":"P1D"}}}\n' \
  | node server.js 2>/dev/null

Interactive CLI testing with chat.js

chat.js is a minimal readline CLI for manually invoking tools without Claude Code. It requires the server to be running. See chat.js for supported commands.


12. Troubleshooting

ErrorCauseFix
tenantId and clientId are requiredEnv vars not loadedCheck .env exists and import "dotenv/config" is the first line in server.js
Application is not authorizedMissing Graph permissionAdd permission in App registrations → Grant admin consent
AuthorizationFailedMissing Azure RBAC roleAssign required role via CLI or Portal
Workspace not onboarded to SentinelWrong workspace nameRun az resource list to find correct name
Cannot find moduleMissing packageRun npm install
MODULE_NOT_FOUND for @azure/identityCorrupted installRun rm -rf node_modules/@azure/identity && npm install @azure/identity
MCP server not appearing in Claude CodeSettings not reloadedRun /mcp in Claude Code or restart it
No response on stdioconsole.log polluting stdoutUse process.stderr.write() for all logging — stdout is reserved for MCP JSON-RPC

13. Bulk User Provisioning

provision-users.js is a standalone one-shot script that creates 20 pre-defined Entra ID test users in bulk. It is independent of the MCP server.

How it works

  • Authenticates using client secret (not certificate) via AZURE_CLIENT_SECRET
  • Calls POST https://graph.microsoft.com/v1.0/users directly for each user
  • Normalises names to email-safe format (strips accents, apostrophes, etc.)
  • All users are created under the Cavalry77.onmicrosoft.com domain with temporary password Cavalry!2026 and forceChangePasswordNextSignIn: true

Before running

  1. Add AZURE_CLIENT_SECRET to your .env file
  2. Update the domain in provision-users.js if your tenant domain differs:
    const upn = `${...}@Cavalry77.onmicrosoft.com`; // ← change this
    
  3. Optionally update the default password to meet your tenant's password policy

Run

node provision-users.js

Expected output:

Acquiring token...
Token acquired. Provisioning 20 users...

[OK]   emma.richardson@Cavalry77.onmicrosoft.com — Created
[OK]   marcus.chen@Cavalry77.onmicrosoft.com — Created
...
Done. 20 created, 0 failed.

Required permissions

PermissionTypePurpose
User.ReadWrite.AllGraph ApplicationCreate Entra ID users

provision-users.js uses AZURE_CLIENT_SECRET. The main server.js uses certificate-based auth (cavalry-sp.combined.pem). The same app registration must have both a client secret and the certificate uploaded if you use both.

Ver o original no GitHub

Bom para

Relacionados