Microsoft Graph Dev MCP

An MCP server that helps you construct and validate Microsoft Graph REST API calls — no authentication required in the server itself.

Tools are loaded on demand by resource category. Ask about SharePoint and the sites tools appear. Ask about files and the OneDrive tools appear. The server starts lean and grows with your needs, and always knows the required permissions for every operation.

What it does

• Constructs valid Graph API request URLs, methods, headers, and bodies
• Validates required and optional parameters
• Returns required Microsoft Graph permissions (delegated and application) for every operation
• Returns ready-to-use fetch code examples
• Links to official Microsoft documentation for every operation
• Explains cross-cutting concepts: pagination, OData queries, throttling, delta sync, batching, and auth
• Loads resource categories on demand — only what you need

Tools

Always available

These tools are loaded immediately — no setup required.

| Tool | Description | |---|---| | list_categories | List all resource categories and which are currently loaded | | load_category | Load tools for a category; triggers tools/list_changed | | search_graph_api | Search Graph API endpoints by keyword; returns a suggestedCategory to load | | graph_build_batch | Build a valid /$batch request body from up to 20 operations | | graph_explain_pagination | How @odata.nextLink works; iterate all pages of results | | graph_explain_odata | $filter, $select, $expand, $orderby, $count, $search with examples | | graph_explain_throttling | 429 handling, Retry-After, exponential backoff pattern | | graph_explain_delta | Delta tokens, change tracking, initial sync vs incremental sync | | graph_explain_batch | JSON batching, dependsOn, response handling | | graph_explain_permissions | Delegated vs application permissions, consent flows, token acquisition |

Resource categories (loaded on demand)

| Category | Tools | What you get | |---|---|---| | users | 8 | Get, list, create, update, delete users; manager; direct reports; delta sync | | files | 11 | OneDrive/SharePoint document library: list, get, upload (<4MB and resumable), create folder, delete, move, copy, search, download URL, delta sync | | mail | 9 | List and get messages, send, create draft, reply, delete, move, list folders, delta sync | | calendar | 8 | List, get, create, update, delete events; find meeting times; get free/busy schedule; delta sync | | groups | 8 | List, get, create, delete groups; list and manage members and owners | | notes | 8 | OneNote notebooks, sections, pages; create and read content | | tasks | 10 | Planner plans and tasks (CRUD); Microsoft To Do lists and tasks | | sites | 12 | SharePoint sites; lists; list items (CRUD); columns | | subscriptions | 5 | Create, list, get, delete, and renew webhook change notification subscriptions |

Example tool output

Every tool returns a structured object with the full request details and required permissions:

{
  "endpoint": "https://graph.microsoft.com/v1.0/sites/{siteId}/lists/{listId}/items?expand=fields",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {token}"
  },
  "pathParams": { "siteId": "contoso.sharepoint.com,abc123", "listId": "list456" },
  "queryParams": { "expand": "fields" },
  "body": null,
  "description": "List items in list list456.",
  "docsUrl": "https://learn.microsoft.com/en-us/graph/api/listitem-list",
  "codeExample": "const response = await fetch('...', { method: 'GET', headers: { Authorization: 'Bearer {token}' } });\nconst data = await response.json();",
  "requiredPermissions": {
    "delegated": ["Sites.Read.All"],
    "application": ["Sites.Read.All"]
  },
  "notes": "Column values are returned under the 'fields' property. This request already includes ?expand=fields. Without it the items array would contain only metadata, not column data."
}

Installation

The recommended way to run this server is via npx — no local install needed.

npx -y @stubbedev/ms-graph-dev-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ms-graph-dev": {
      "command": "npx",
      "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add ms-graph-dev -- npx -y @stubbedev/ms-graph-dev-mcp

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "ms-graph-dev": {
      "command": "npx",
      "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Cursor

Open Settings → MCP and add a new server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ms-graph-dev": {
      "command": "npx",
      "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ms-graph-dev": {
      "command": "npx",
      "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Zed

Edit your settings.json (open via Zed → Settings → Open Settings):

{
  "context_servers": {
    "ms-graph-dev": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
      }
    }
  }
}

OpenCode

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "ms-graph-dev": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Codex (OpenAI)

Edit ~/.codex/config.json:

{
  "mcpServers": {
    "ms-graph-dev": {
      "command": "npx",
      "args": ["-y", "@stubbedev/ms-graph-dev-mcp"]
    }
  }
}

Development

git clone https://github.com/stubbedev/ms-graph-dev-mcp.git
cd ms-graph-dev-mcp
npm install
npm run build
npm start

For live reload during development:

npm run dev

Test with MCP Inspector

npx @modelcontextprotocol/inspector npx -y @stubbedev/ms-graph-dev-mcp

License

MIT