Skip to content
BranchesTags

Repository files navigation

Agent 365 MCP

MCP (Model Context Protocol) server for Microsoft 365 integration with AI coding assistants.

Access SharePoint, Word, Teams, Outlook, Calendar, Excel, and M365 Copilot directly from any MCP-compatible client.

Supported Clients

  • Claude Code (Anthropic CLI)
  • Claude Desktop (Anthropic app)
  • VS Code with GitHub Copilot
  • GitHub Copilot with MCP support
  • Cursor
  • Any MCP-compatible AI assistant

Features

  • SharePoint & OneDrive: Read/write files, search, share
  • Word: Read documents, add comments, create new docs
  • Teams: Read chats, channels, post messages
  • Outlook Mail: Read/send emails
  • Calendar: Manage events
  • Excel: Read/write spreadsheets
  • M365 Copilot: Search and chat
  • User Profile: Org chart, manager info

80+ tools available. Dangerous operations (delete/remove) are filtered for safety.

Prerequisites

  1. Copilot for Microsoft 365 license assigned to your account
  2. Organization setup (one-time per organization):
    • Create Entra ID app registration
    • Grant admin consent for Agent 365 permissions
    • Users can get Tenant ID and Client ID from entra.microsoft.com (or from IT admin if they don't have access)

Quick Start

Option 1: Zero-Config (If IT provided env vars)

Just add to your MCP config - authentication happens automatically on first use:

{
  "mcpServers": {
    "agent365": {
      "command": "npx",
      "args": ["-y", "github:rapyuta-robotics/agent365-mcp", "serve"],
      "env": {
        "AGENT365_TENANT_ID": "your-tenant-id",
        "AGENT365_CLIENT_ID": "your-client-id"
      }
    }
  }
}

On first use, your browser opens automatically for Microsoft login. That's it!

Option 2: Interactive Setup

Run the setup wizard which configures everything for you:

npx github:rapyuta-robotics/agent365-mcp setup

This will:

  1. Prompt for your Tenant ID and Client ID (get from entra.microsoft.com, or IT admin if you don't have access)
  2. Open Microsoft login in your browser
  3. Auto-configure Claude Code and/or VS Code
  4. Store refresh token for ~90 day sessions

That's it! Restart your coding assistant and the tools are available.

Manual Installation

If you prefer manual setup:

1. Authenticate

Get your values from entra.microsoft.com:

  • Tenant ID: Entra Home page
  • Client ID: Home > App Registrations > Agent 365 MCP

If you don't have Entra access, ask your IT admin.

export AGENT365_TENANT_ID="your-tenant-id"
export AGENT365_CLIENT_ID="your-client-id"
npx github:rapyuta-robotics/agent365-mcp auth

2. Configure your MCP client

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "agent365": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:rapyuta-robotics/agent365-mcp", "serve"],
      "env": {
        "AGENT365_TENANT_ID": "your-tenant-id",
        "AGENT365_CLIENT_ID": "your-client-id"
      }
    }
  }
}

VS Code

Quick way: Ctrl+Shift+P (or Cmd+Shift+P on Mac) → MCP: Open User Configuration to directly edit your MCP config file.

Add this to your MCP user config (~/.vscode/mcp.json):

{
  "servers": {
    "agent365": {
      "command": "npx",
      "args": ["-y", "github:rapyuta-robotics/agent365-mcp", "serve"],
      "env": {
        "AGENT365_TENANT_ID": "your-tenant-id",
        "AGENT365_CLIENT_ID": "your-client-id"
      }
    }
  }
}

Alternative - Add MCP Server UI:

  1. Ctrl+Shift+P → MCP: Add Server
  2. Select: Command (stdio)
  3. Command: npx
  4. Args: -y github:rapyuta-robotics/agent365-mcp serve
  5. Name: agent365
  6. Scope: User Settings or Workspace
  7. Then edit config to add the env section above

Claude Desktop

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Or: Open Claude Desktop → Settings → Developer → Edit Config

{
  "mcpServers": {
    "agent365": {
      "command": "npx",
      "args": ["-y", "github:rapyuta-robotics/agent365-mcp", "serve"],
      "env": {
        "AGENT365_TENANT_ID": "your-tenant-id",
        "AGENT365_CLIENT_ID": "your-client-id"
      }
    }
  }
}

After saving, completely quit and restart Claude Desktop to load the new configuration.

GitHub Copilot / Cursor

Use similar MCP configuration in your editor's settings. Consult your editor's MCP documentation for the exact location.

  1. Restart your editor - The tools will be available.

Check Status

npx github:rapyuta-robotics/agent365-mcp status

Re-authenticate (when token expires)

npx github:rapyuta-robotics/agent365-mcp auth

IT Admin Setup

See ADMIN.md for detailed setup instructions.

Quick Start

  1. Create Service Principal (one-time)
curl -O https://raw.githubusercontent.com/microsoft/Agent365-devTools/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
pwsh ./New-Agent365ToolsServicePrincipalProdPublic.ps1
  1. Create App Registration
az ad app create --display-name "Agent 365 MCP" --sign-in-audience "AzureADMyOrg"
az ad app update --id <app-id> --is-fallback-public-client true
az ad app update --id <app-id> --public-client-redirect-uris "http://localhost"
az ad sp create --id <app-id>
  1. Add Permissions & Grant Consent

See ADMIN.md for complete permission setup and admin consent commands.

  1. Distribute to Users

Provide users with:

  • Tenant ID: az account show --query tenantId -o tsv
  • Client ID: The app ID from step 2

Available Tools

Prefix Service Tools
sharepoint_* SharePoint/OneDrive File operations, search, share
word_* Word Read docs, comments, create
teams_* Teams Chats, channels, messages
mail_* Outlook Email read/send/reply
calendar_* Calendar Events, scheduling
me_* Profile User/org info
excel_* Excel Spreadsheet operations
copilot_* M365 Copilot Search, chat

Security

  • Each user authenticates with their own M365 account
  • Access is limited to what the user can access in M365
  • Dangerous operations (delete, remove) are blocked by default
  • Tokens stored locally in ~/.agent365-mcp/
  • Tokens expire after 1 hour and auto-refresh on next use

Configuration

Optional environment variables to customize behavior:

Variable Default Description
AGENT365_TENANT_ID (required) Azure tenant ID
AGENT365_CLIENT_ID (required) App registration client ID
AGENT365_TOKEN_PATH ~/.agent365-mcp/tokens.json Custom token storage path
AGENT365_MAX_RESPONSE_SIZE 50000 Max characters before truncation
AGENT365_TIMEOUT 60000 Request timeout in milliseconds
AGENT365_LARGE_FILE_DIR (none) Directory to save large responses
AGENT365_LARGE_FILE_THRESHOLD 100000 Size threshold for file save
AGENT365_ALLOW_DANGEROUS false Enable dangerous tools (delete/remove)
AGENT365_DISABLED_SERVERS (none) Comma-separated servers to disable

Large Response Handling

By default, responses over 50KB are truncated. For better handling of large data:

{
  "env": {
    "AGENT365_LARGE_FILE_DIR": "/tmp/agent365-responses"
  }
}

When set, responses over 100KB are saved to files instead of truncated. The agent receives the filepath and can use Read tools to access the content.

Disabling Servers

If you don't have Copilot license or want to disable specific services:

{
  "env": {
    "AGENT365_DISABLED_SERVERS": "copilot,excel"
  }
}

The proxy also auto-detects license errors and gracefully disables affected servers.

Full Configuration Example

{
  "mcpServers": {
    "agent365": {
      "command": "npx",
      "args": ["-y", "github:rapyuta-robotics/agent365-mcp", "serve"],
      "env": {
        "AGENT365_TENANT_ID": "your-tenant-id",
        "AGENT365_CLIENT_ID": "your-client-id",
        "AGENT365_MAX_RESPONSE_SIZE": "100000",
        "AGENT365_TIMEOUT": "120000",
        "AGENT365_LARGE_FILE_DIR": "/tmp/agent365",
        "AGENT365_DISABLED_SERVERS": "copilot"
      }
    }
  }
}

Troubleshooting

"Scope not present" error

Your token doesn't have the required permissions. Re-authenticate:

npx github:rapyuta-robotics/agent365-mcp auth

"No valid token" error

Token expired or not authenticated. Run:

npx github:rapyuta-robotics/agent365-mcp auth

Tools not loading

  1. Check status: npx github:rapyuta-robotics/agent365-mcp status
  2. Verify Copilot license is assigned to your account
  3. Confirm Tenant ID (Entra Home) and Client ID (Home > App Registrations > Agent 365 MCP) in your config, or ask IT admin to verify admin consent if you don't have access

Large response errors / Content truncated

Some M365 queries return very large responses. The proxy automatically handles this:

  1. Use more specific queries (date ranges, filters, pagination)
  2. Set AGENT365_LARGE_FILE_DIR to save large responses to files
  3. Increase AGENT365_MAX_RESPONSE_SIZE for larger truncation limit
  4. Use M365 Copilot search instead of listing all items

Request timeout

Long-running queries may timeout. Increase timeout with AGENT365_TIMEOUT (in milliseconds).

Documentation

  • ADMIN.md - IT administrator setup guide with detailed Azure CLI commands
  • ARCHITECTURE.md - Technical architecture, data flows, and system design
  • AGENTS.md - AI agent integration guide with tool selection patterns

License

MIT

About

MCP server for Microsoft 365 integration with AI coding assistants

Resources

Readme
Activity
Custom properties

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages