Graph Mail MCP

Microsoft 365 메일용 로컬 stdio Model Context Protocol 서버입니다. Microsoft Graph를 통해 제어된 Outlook/Exchange Online 검색, 읽기, 스레드, 첨부 파일 및 초안 워크플로를 제공합니다.

메시지를 보내거나, 삭제하거나, 이동하거나, 복사하거나, 보관하거나, 읽음으로 표시하지 않습니다. 원시 Graph URL, 원시 OData 및 제한 없는 Graph 요청은 노출되지 않습니다.

요구 사항

• Microsoft Edge가 설치된 Windows

• Node.js 22+

• Exchange Online이 포함된 Microsoft 365 회사 또는 학교 계정

• 위임된 Mail.ReadWrite 권한

개인 Microsoft 계정은 기본적으로 비활성화되어 있습니다. 공유 사서함은 추가로 Exchange 위임과 Mail.ReadWrite.Shared가 필요합니다.

설치

git clone https://github.com/hanhandly/graph-mail-mcp.git
Set-Location graph-mail-mcp
npm ci
npm run build
Copy-Item config.example.json config.local.json

config.local.json은 Git에서 무시됩니다. 인증 전에 특히 tenant, allowedMailboxScopes 및 공유 사서함 설정을 검토하세요.

인증

node dist\cli.js -c config.local.json doctor
node dist\cli.js -c config.local.json auth login --account-hint user@contoso.com
node dist\cli.js -c config.local.json auth status

로그인은 격리된 Microsoft Edge 프로필을 열고 위임된 인증에 Graph Explorer를 사용합니다. Playwright는 로그인을 클릭하고, 힌트된 계정을 선택하며, 필요한 메일 권한이 이미 동의되었는지 확인합니다. 동의된 경우 인증이 자동으로 계속되고, 그렇지 않으면 CLI가 사용자에게 부여해야 하는 권한을 알려줍니다. Playwright는 동의를 클릭하지 않습니다. MFA 및 동의 확인은 사용자 제어로 유지됩니다. auth status는 메타데이터만 반환하며 토큰을 표시하지 않습니다.

MCP 클라이언트 구성

클라이언트의 MCP 구성에서 절대 경로를 사용하세요:

{
  "mcpServers": {
    "graph-mail": {
      "command": "node",
      "args": [
        "C:\\Tools\\graph-mail-mcp\\dist\\cli.js",
        "-c",
        "C:\\Tools\\graph-mail-mcp\\config.local.json",
        "serve"
      ],
      "cwd": "C:\\Tools\\graph-mail-mcp"
    }
  }
}

일부 클라이언트는 다른 외부 키를 사용하지만 command, args 및 cwd 값은 동일합니다. serve 앞에 -c <config-path>를 유지하세요. 서버는 stdio를 사용하며 네트워크 포트를 열지 않습니다.

MCP 클라이언트를 다시 시작한 후 다음을 호출하세요:

1. mail_auth_status

2. mail_list_folders

3. mail_search_messages

도구

초안 업데이트는 이 MCP에서 생성 및 등록된 초안으로 제한됩니다. 보내기 도구는 없습니다.

보안

Graph 전송은 기본 거부 정책 방화벽과 타입이 지정된 요청 컴파일러를 사용합니다. 토큰은 저장소 외부에 저장되며 기본적으로 Windows DPAPI로 보호됩니다. 로그 및 도구 응답은 액세스 토큰, 쿠키 또는 권한 부여 헤더를 노출해서는 안 됩니다.

Graph Explorer는 공유 애플리케이션에 이전에 동의된 권한을 반환할 수 있습니다. 서버는 Mail.Send를 거부하고 런타임 요청을 제한하지만, 엄격한 최소 권한 토큰이 필요한 배포는 전용 앱 등록 또는 제한된 인증 공급자를 사용해야 합니다.

보안, 도구 참조, 구성 예시 및 아키텍처를 참조하세요.