mcp-viva-engage

Claude AI를 Viva Engage(Yammer)에 연결하는 오픈 소스 MCP(Model Context Protocol) 서버입니다. Claude와의 자연스러운 대화를 통해 홈 네트워크 커뮤니티를 탐색하고, 게시물을 검색하며, 대화를 읽고, 답글을 게시할 수 있습니다.

제작자: Pranav Joshi

주요 기능

연결 후 Claude에게 다음과 같이 요청할 수 있습니다:

• "내가 속한 Viva Engage 커뮤니티는 무엇인가요?"

• "Business Central 오류에 관한 게시물을 검색해줘"

• "개발자 커뮤니티의 최신 대화는 무엇인가요?"

• "그 스레드에 ...라고 답글 달아줘"

• "내 Viva Engage 피드를 보여줘"

Related MCP server: linkedin-mcp-server

중요 제한 사항 — 홈 네트워크 전용

이 MCP 서버는 홈 네트워크(로그인 자격 증명과 연결된 기본 조직 네트워크)에서만 작동합니다.

외부 네트워크에 액세스할 수 없는 이유는 무엇인가요?

Viva Engage는 두 가지 유형의 네트워크를 지원합니다:

• 홈 네트워크 — 기본 조직(예: 회사 Viva Engage)

• 외부 네트워크 — 게스트 멤버로 참여 중인 다른 조직의 커뮤니티(예: Microsoft의 BC Partners 커뮤니티)

Yammer REST API(www.yammer.com/api/v1)는 어떤 매개변수나 토큰을 사용하든 홈 네트워크의 데이터만 반환합니다. 외부 네트워크는 전체 웹 기반 로그인을 거친 후에만 사용할 수 있는 브라우저 세션 쿠키가 필요하며, 이는 API 호출만으로는 복제할 수 없습니다.

Microsoft의 최신 Graph API(graph.microsoft.com) 또한 외부 네트워크를 지원하지 않으며, 자체 테넌트 내의 네이티브 모드 네트워크에서만 작동합니다.

이는 이 MCP 서버의 제한이 아닌 Microsoft API의 제한입니다. 향후 Microsoft가 API를 확장하여 외부 네트워크를 지원하게 되면, 이 서버도 업데이트하여 지원할 수 있습니다.

작동 방식

You ask Claude a question
        ↓
Claude calls this MCP server
        ↓
Server calls Viva Engage API using YOUR login
        ↓
Returns data only YOU can already see
        ↓
Claude answers your question

개인정보 보호: 모든 사용자는 자신의 Azure 앱을 등록하고 자신의 Microsoft 자격 증명을 사용합니다. 데이터는 다른 사람의 인프라를 거치지 않습니다. 로그인 토큰은 사용자의 컴퓨터에만 암호화되어 저장됩니다.

사전 요구 사항

• Node.js v18 이상

• Claude Desktop

• Viva Engage 액세스 권한이 있는 Microsoft 회사/학교 계정

1단계 — Azure 앱 등록

이 설정은 한 번만 수행하면 됩니다(약 10분 소요). 본인의 Microsoft 계정으로 직접 앱을 등록합니다. 다른 사람은 사용자의 앱을 사용할 수 없으며, 오직 사용자의 자격 증명에만 연결됩니다.

1. portal.azure.com에 접속하여 회사/학교 Microsoft 계정으로 로그인합니다.

2. **"App registrations"(앱 등록)**를 검색하고 **"+ New registration"(새 등록)**을 클릭합니다.

3. 다음 내용을 입력합니다:

   • 이름: mcp-viva-engage (원하는 이름으로 설정 가능)

   • 지원되는 계정 유형: Multiple Entra ID tenants → Allow all tenants 선택

   • 리디렉션 URI:

     • 플랫폼 = Public client/native (mobile & desktop)

     • URI = http://localhost

4. **"Register"(등록)**를 클릭합니다.

5. 개요 페이지에서 다음 두 가지를 복사하여 저장합니다:

   • Application (client) ID (애플리케이션(클라이언트) ID)

   • Directory (tenant) ID (디렉터리(테넌트) ID)

API 권한 추가

1. 왼쪽 사이드바에서 **"API permissions"(API 권한)**를 클릭합니다.

2. "+ Add a permission"(권한 추가) → "All APIs"(모든 API) 탭 → "Yammer" 검색을 클릭합니다.

3. "Yammer" → **"Delegated permissions"(위임된 권한)**를 클릭합니다.

4. 다음 네 가지 권한을 체크합니다:

   • ✅ user_impersonation

   • ✅ Community.Read.All

   • ✅ EngagementConversation.ReadWrite.All

   • ✅ Storyline.ReadWrite.All

5. **"Add permissions"(권한 추가)**를 클릭합니다.

회사/학교 계정 참고: 처음 로그인하기 전에 조직의 IT 관리자가 이 앱에 대한 동의를 승인해야 할 수 있습니다. 이는 일회성 단계입니다. 서버를 처음 실행할 때 로그인 화면에서 직접 승인 요청을 제출할 수 있습니다.

2단계 — 복제 및 빌드

# Clone the repo
git clone https://github.com/pranav4186/mcp-viva-engage.git
cd mcp-viva-engage

# Install dependencies
npm install

# Build
npm run build

3단계 — 자격 증명 구성

예제 env 파일을 복사합니다:

# Windows
copy .env.example .env

# Mac/Linux
cp .env.example .env

.env 파일을 열고 1단계에서 얻은 값을 입력합니다:

AZURE_CLIENT_ID=your-application-client-id-here
AZURE_TENANT_ID=your-directory-tenant-id-here

중요: .env 파일을 GitHub에 커밋하지 마십시오. 이를 방지하기 위해 이미 .gitignore에 포함되어 있습니다.

4단계 — Claude Desktop에 연결

Claude Desktop 구성 파일을 엽니다:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers 섹션에 viva-engage 서버를 추가합니다:

{
  "mcpServers": {
    "viva-engage-mcp": {
      "command": "node",
      "args": ["C:/path/to/mcp-viva-engage/dist/server.js"],
      "env": {
        "AZURE_CLIENT_ID": "your-application-client-id-here",
        "AZURE_TENANT_ID": "your-directory-tenant-id-here"
      }
    }
  }
}

C:/path/to/mcp-viva-engage를 리포지토리를 복제한 실제 경로로 바꾸십시오. Windows 경로는 슬래시 / 또는 이중 백슬래시 \\를 사용할 수 있습니다.

저장 후 Claude Desktop을 완전히 종료하고 다시 시작하십시오.

5단계 — 첫 로그인

Claude에게 Viva Engage에 대해 처음 질문하면:

1. Microsoft 로그인 페이지가 포함된 브라우저 창이 자동으로 열립니다.

2. 회사/학교 Microsoft 계정으로 로그인합니다.

3. 권한을 승인합니다.

4. 브라우저에 **"Login successful!"(로그인 성공!)**이 표시됩니다.

5. Claude가 요청을 완료합니다.

세션은 컴퓨터에 암호화되어 보관됩니다. Claude Desktop을 다시 시작할 때 다시 로그인해야 할 수도 있습니다.

사용 가능한 도구

보안 및 개인정보 보호

프로젝트 구조

mcp-viva-engage/
├── src/
│   ├── auth/
│   │   └── auth.ts          # Microsoft OAuth login with DPAPI encrypted cache
│   ├── yammerClient.ts      # Viva Engage / Yammer API client
│   └── server.ts            # MCP server and tool definitions
├── .env.example             # Template — copy to .env and fill in your values
├── .gitignore               # Prevents .env from being committed
├── package.json
├── tsconfig.json
└── README.md

문제 해결

첫 로그인 시 "승인 필요(Approval required)" 발생

조직에서 새 앱에 대해 관리자 승인을 요구하는 경우입니다. IT 관리자에게 Azure 포털 → Enterprise Applications → mcp-viva-engage 찾기 → 관리자 승인 부여를 요청하십시오. 이는 일회성 작업입니다.

Claude Desktop에 서버가 표시되지 않음

구성 파일을 편집한 후 Claude Desktop을 완전히 종료하고 다시 시작하십시오. dist/server.js 경로가 올바른지 확인하십시오.

재시작 후 다시 로그인해야 함

암호화된 토큰이 만료되었을 수 있습니다. 다시 로그인하면 세션이 캐시됩니다.

홈 네트워크 커뮤니티만 보임

정상적인 동작입니다. 위의 중요 제한 사항 섹션을 참조하십시오. Yammer REST API는 홈 네트워크 액세스만 지원합니다.

Windows 경로 문제

구성 파일에서 슬래시 C:/path/to/dist/server.js 또는 이중 백슬래시 C:\\path\\to\\dist\\server.js를 사용하십시오.

알려진 제한 사항

• 홈 네트워크 전용 — 외부 네트워크(예: Microsoft BC Partners 커뮤니티)는 공개된 Microsoft API를 통해 액세스할 수 없습니다. 위 설명을 참조하십시오.

• 속도 제한 — Yammer API는 사용자당, 앱당 30초마다 10개의 요청을 허용합니다.

• 읽기 전용 검색 — 검색 결과는 Viva Engage가 인덱싱하는 내용으로 제한됩니다.

로드맵

• [ ] 사용자가 로컬 설정을 할 필요가 없도록 원격 커넥터로 전환

• [ ] 대규모 커뮤니티 피드에 대한 페이지 매김 지원 추가

• [ ] 더 안전한 토큰 저장을 위한 Windows 자격 증명 관리자 지원

• [ ] 향후 Microsoft가 API 지원을 추가할 경우 외부 네트워크 지원

라이선스

MIT — 자세한 내용은 LICENSE를 참조하십시오.

면책 조항

이 프로젝트는 독립적인 오픈 소스 프로젝트이며 Microsoft 또는 Viva Engage와 제휴, 보증 또는 지원을 받지 않습니다. 사용에 따른 책임은 사용자 본인에게 있습니다.