Outlook MCP Sunucusu

Microsoft 365 posta kutusunu MCP (Model Context Protocol) üzerinden internete açan, tek başına çalışan bir Node servisi. Claude Desktop bu sunucuya bağlanıp posta kutusunda arama yapabilir, mesajları okuyabilir, ekleri indirebilir ve (açıkça izin verilirse) mail gönderebilir.

Ana projeden (parasut-ops-panel) tamamen bağımsızdır: Replit'e özgü hiçbir SDK kullanmaz, kendi package.json dosyası vardır. Render, Railway, Fly veya yeni bir Replit projesinde aynen çalışır.

1. Önce şunu bilin: hangi posta kutusuna erişilebilir?

Bu sunucu app-only (client credentials) kimlik doğrulaması kullanır. Microsoft 365 tenant'ında bir ApplicationAccessPolicy hangi kutulara app-only erişilebileceğini sınırlar. Test edilmiş güncel durum:

Yani bu sunucu bulutta bir yerde çalıştığında yalnızca finans@ kutusunu okuyabilir.

omererdogan@ kutusunu da okumak istiyorsanız iki seçenek var:

1. Tenant yöneticisinden politikayı genişletmesini isteyin. Doğru çözüm budur ve sunucuda hiçbir kod değişikliği gerektirmez. Yöneticinin çalıştıracağı komut (Exchange Online PowerShell):

   # Mevcut politikayı gör
   Get-ApplicationAccessPolicy | Format-List AppId,PolicyScopeGroupId,AccessRight
   
   # İzin verilen kullanıcı grubuna omererdogan@ ekleyin (grup adı tenant'a göre değişir)
   Add-DistributionGroupMember -Identity "<mcp-izinli-kutular-grubu>" `
     -Member omererdogan@rsresearch.net
   
   # Doğrulama
   Test-ApplicationAccessPolicy -Identity omererdogan@rsresearch.net -AppId <AZURE_CLIENT_ID>

   Sonuç AccessCheckResult: Granted dönerse MCP_MAILBOXES listesine adresi ekleyip servisi yeniden başlatmanız yeterli.

2. Yalnızca finans@ ile devam edin. Hiçbir şey yapmanıza gerek yok, varsayılan bu.

Gönderme (MCP_ALLOW_SEND) varsayılan olarak kapalıdır ve açsanız bile finans@ kutusundan app-only gönderim 403 döner. Gönderim gerekiyorsa Azure uygulamasına Mail.Send Application izni verilmeli, admin onayı alınmalı ve erişim politikası o kutuyu kapsamalıdır.

Related MCP server: Agent Email

2. Araçlar

search_mail hakkında bilmeniz gereken iki şey

a) İki mod vardır ve araç otomatik seçer.

• query, to veya subject verilirse → metin arama modu (Graph KQL). Bu modda Graph sonuçları alaka düzeyine göre sıralar, tarihe göre değil; tarih sınırı da gün hassasiyetindedir.

• Yalnızca tarih / from / hasAttachments verilirse → filtre modu. Sonuçlar en yeniden en eskiye sıralanır.

Bu ayrım Graph'ın bir kısıtından geliyor: $search ile $filter ve $orderby aynı istekte kullanılamaz.

b) Sonuçlar sayfalıdır. Varsayılan tarih penceresi son 730 gün (~2 yıl). Tek çağrıda en fazla 100 mesaj döner. Devamı için dönen nextCursor değerini bir sonraki çağrıda cursor parametresine geçirin. Claude bunu kendiliğinden yapar; siz sadece "devam et" demeniz yeterli.

3. Yerelde çalıştırma

cd mcp-outlook
cp .env.example .env      # değerleri doldurun
npm install
npm run build
npm start

Sağlık kontrolü: curl http://localhost:5000/healthz

MCP_AUTH_TOKEN üretmek için: openssl rand -hex 32

4. Render.com'a kurulum (adım adım)

Render seçilmesinin sebebi: bu Replit projesinin cloud_run dağıtımı askıya alınmış durumda ve açılması Replit Support gerektiriyor.

1. Kodu GitHub'a gönderin. Render bir Git reposundan deploy eder. Bu klasörün içeriği kendi başına bir deponun kökü olacak şekilde tasarlandı: package.json, render.yaml ve src/ doğrudan kökte durmalı. Sarmalayıcı bir mcp-outlook/ klasörünün içine koymayın — Render blueprint'i yalnızca depo kökünde arar.

   Yine de daha büyük bir deponun alt klasörü olarak tutmak isterseniz: render.yaml dosyasını depo köküne taşıyın ve içine rootDir: <klasör-adı> satırını ekleyin.

2. Render panelinde New → Blueprint → repoyu seçin. Render kökteki render.yaml dosyasını okuyup servisi hazırlar.

   Blueprint kullanmak istemezseniz New → Web Service ile elle de kurabilirsiniz:

   Alan	Değer
   Root Directory	(boş bırakın — depo kökü)
   Runtime	Node
   Build Command	npm ci && npm run build
   Start Command	npm start
   Health Check Path	/healthz

3. Ortam değişkenlerini girin (Render → servis → Environment):

   Anahtar	Değer
   AZURE_TENANT_ID	Ana projedekiyle aynı
   AZURE_CLIENT_ID	Ana projedekiyle aynı
   AZURE_CLIENT_SECRET	Ana projedekiyle aynı
   MCP_AUTH_TOKEN	openssl rand -hex 32 çıktısı
   MCP_MAILBOXES	finans@rsresearch.net

   PORT girmeyin — Render kendisi enjekte eder.

4. Deploy'u bekleyin, sonra doğrulayın:

   curl https://<servis-adi>.onrender.com/healthz

   {"status":"ok",...} görmelisiniz.

5. Planı seçerken dikkat: Render'ın ücretsiz katmanı 15 dakika boştan sonra servisi uyutur; uyandırma 30–60 saniye sürer ve Claude bu sürede zaman aşımına düşebilir. Düzenli kullanacaksanız ücretli (Starter) plan gerekir. render.yaml içinde plan: starter yazılıdır.

Alternatif: yeni bir Replit projesi

mcp-outlook klasörünü yeni bir Replit projesine kopyalayın, aynı ortam değişkenlerini Secrets olarak girin (PORT=5000), çalıştırma komutunu npm run build && npm start yapın ve projeyi Autoscale Deployment olarak yayınlayın. Adres https://<proje>.replit.app/mcp olur. Adımlar aynıdır.

5. Claude Desktop'a bağlama

claude_desktop_config.json dosyası yalnızca stdio sunucuları kabul eder. Doğrudan "url": "..." yazarsanız Claude Desktop girdiyi sessizce siler. Bu yüzden mcp-remote adlı köprüyü kullanıyoruz: Claude Desktop ile stdio, sunucumuzla Streamable HTTP konuşur.

Dosyanın yeri:

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

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

İçerik:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<servis-adi>.onrender.com/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer BURAYA_MCP_AUTH_TOKEN"
      }
    }
  }
}

Üç ayrıntı önemli:

• Authorization:${AUTH_HEADER} ifadesinde iki nokta üst üste sonrasında boşluk yoktur. Claude Desktop argümanlardaki boşlukları bozar; bu yüzden token'ı env içine koyup değişken olarak enjekte ediyoruz. Bearer kelimesi env değerinin içindedir.

• --transport http-only şart: bu sunucu stateless çalışır, SSE akışı sunmaz. Bu bayrak olmadan mcp-remote önce SSE deneyip gereksiz yere bekler.

• Node 18+ kurulu olmalı (npx bunun için gerekli).

Kaydedin ve Claude Desktop'ı tamamen kapatıp yeniden açın. Ayarlar → Connectors altında outlook görünmeli ve araçlar listelenmelidir.

Deneyin: "finans kutusunda son 6 ayda gönderilen, konusunda fatura geçen mailleri listele."

Claude.ai (tarayıcı) veya mobil uygulama

Web arayüzündeki "Custom Connector" özelliği bearer token değil OAuth 2.0 bekler. Bu sunucu OAuth uygulamaz, dolayısıyla Claude.ai üzerinden doğrudan bağlanamazsınız. Masaüstü uygulaması + mcp-remote yolunu kullanın.

6. Güvenlik

• MCP_AUTH_TOKEN bir paroladır. Onu bilen herkes MCP_MAILBOXES listesindeki kutuların tamamını okuyabilir. Sohbete, ekran görüntüsüne veya repoya yazmayın.

• MCP_MAILBOXES bir güvenlik sınırıdır. Azure app-only token teknik olarak tenant'taki her kutuya erişebilir; sunucu her istekte gelen adresi bu listeye karşı doğrular ve listede olmayanı reddeder. Listeyi dar tutun.

• Yazma varsayılan olarak kapalıdır. MCP_ALLOW_SEND=true yapmadıkça send_mail aracı Claude'a hiç gösterilmez.

• Token'ı değiştirmeniz gerekirse Render'da değeri güncelleyin, servisi yeniden başlatın ve claude_desktop_config.json içindeki değeri de güncelleyin.

7. Sorun giderme