MCP Sunucu Nasıl Kurulur? Claude Desktop ve Cursor Rehberi

Claude’a “şu klasördeki dosyaları oku” veya “GitHub’daki o issue’yu getir” diyebilmek için yıllarca karmaşık prompt zincirleri ya da özel API entegrasyonları gerekiyordu. MCP bu köprüyü standartlaştırdı.

Bu rehberde MCP sunucularını Claude Desktop, Cursor ve VS Code’a nasıl bağlayacağını adım adım gösteriyorum. Filesystem, Brave Search ve GitHub için tam JSON konfigürasyonları ve sık karşılaşılan hata çözümleri dahil.

MCP Nedir?

Model Context Protocol (MCP), yapay zeka istemcileri (Claude, Cursor gibi) ile dış araçlar arasında standart bir iletişim katmanı tanımlar. İstemci tarafında oturan LLM, protokol üzerinden araçları, kaynakları ve şablonlu prompt’ları çağırabilir.

WebMCP ile karıştırma: WebMCP, W3C’nin tarayıcı standardı. Bu rehberdeki MCP ise Anthropic’in geliştirici ekosistemi için tanımladığı farklı bir protokol. İkisi de aynı kısaltmayı kullanıyor, ama birbirinden bağımsız.

Mimari şöyle çalışır:

İstemci (Claude / Cursor)
       │
       │  JSON-RPC 2.0
       ▼
  MCP Sunucusu
  ├── tools/       → fonksiyon çağrıları
  ├── resources/   → dosya veya veri kaynakları
  └── prompts/     → şablon prompt'lar
       │
       ▼
Dış Sistem (Filesystem, GitHub, DB, API…)

Function calling’in LLM’leri gerçek sistemlere nasıl bağladığına zaten aşinaysan MCP’yi “araç tanımlarını ve taşıma katmanını standartlaştıran bir üst çerçeve” olarak düşünebilirsin.

Ön Gereksinimler

Kuruluma geçmeden önce şunlar hazır olmalı:

• Node.js 18+ (çoğu resmi MCP sunucusu npx ile çalışır)
• Claude Desktop (claude.ai/download adresinden ücretsiz indir)
• Cursor veya VS Code (opsiyonel, sonraki bölümlerde)
• Brave Search için ücretsiz API anahtarı (yalnızca o sunucu için)
• GitHub için Personal Access Token (yalnızca GitHub sunucusu için)

Node.js sürümünü doğrulamak için:

node --version   # v18.0.0 veya üstü
npx --version

Claude Desktop Kurulumu

claude_desktop_config.json Yapısı

Claude Desktop, MCP sunucularını tek bir JSON dosyasından yönetir. Dosyanın yolu işletim sistemine göre değişir:

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

Dosya henüz yoksa elle oluşturabilirsin. Temel yapı şöyle:

{
  "mcpServers": {
    "sunucu-adi": {
      "command": "npx",
      "args": ["-y", "paket-adi"],
      "env": {
        "ANAHTAR": "deger"
      }
    }
  }
}

Her mcpServers girdisi bağımsız bir sunucu tanımıdır. command alanı çalıştırılacak binary’yi, args parametreleri belirtir. env ise o sunucuya özgü ortam değişkenlerini taşır. API anahtarları buraya girer, komut satırına değil.

Önemli: Dosyayı her değiştirdiğinde Claude Desktop’u tamamen kapatıp yeniden açman gerekir. Yalnızca sekmeyi kapatmak yetmez.

Filesystem MCP Kurulumu

Filesystem sunucusu, Claude’un belirttiğin klasörlerdeki dosyaları okumasına ve yazmasına izin verir. Kurulum gerektirmez; npx ile doğrudan çalışır.

claude_desktop_config.json içine şunu ekle:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/kullanici/Documents",
        "/Users/kullanici/Desktop"
      ]
    }
  }
}

args listesindeki son iki eleman erişime açılacak klasör yollarıdır. İstediğin kadar ekleyebilirsin; listelenmemiş klasörlere Claude erişemez. Windows’ta yol biçimi farklıdır:

"args": [
  "-y",
  "@modelcontextprotocol/server-filesystem",
  "C:\\Users\\kullanici\\Documents"
]

Kurulum sonrası Claude Desktop’u yeniden başlat ve şunu dene: “Documents klasörümdeki en son değiştirilen 5 dosyayı listele.” Claude dosya sistemine erişebildiğinde yanıt doğrudan gelir.

Brave Search MCP Kurulumu

Brave Search sunucusu, Claude’un gerçek zamanlı web araması yapmasını mümkün kılar. Önce Brave Search API sayfasından ücretsiz anahtar alman gerekiyor (ayda 2000 sorgu ücretsiz).

Konfigürasyon:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA-buraya-anahtarini-yaz"
      }
    }
  }
}

API anahtarını env bloğuna koy, asla args içine yazma. Birden fazla sunucuyu aynı dosyada tanımlamak için mcpServers bloğuna sırayla ekleme yap:

{
  "mcpServers": {
    "filesystem": { ... },
    "brave-search": { ... }
  }
}

GitHub MCP Kurulumu

GitHub sunucusu, issue okuma, PR inceleme ve repository içeriğine erişim için kullanılır. Personal Access Token (PAT) gerektirir. GitHub’da Settings → Developer settings → Personal access tokens → Fine-grained tokens yolunu izleyerek token oluştur; repo kapsamını işaretle.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tokenini_buraya_yaz"
      }
    }
  }
}

Kurulumdan sonra şunu test et: “anthropics/anthropic-sdk-python reposundaki son 3 açık issue’yu getir.” GitHub sunucusu çalışıyorsa liste doğrudan gelir.

Üç sunucuyu bir arada çalıştıran tam claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/kullanici/Documents"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA-anahtarin"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tokenin"
      }
    }
  }
}

Cursor’a MCP Ekleme

.cursor/mcp.json ile Yapılandırma

Cursor 0.43 ve üzeri sürümler MCP’yi yerleşik olarak destekler. Konfigürasyon dosyası ~/.cursor/mcp.json adresinde bulunur (global yapılandırma):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/kullanici/Projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tokenin"
      }
    }
  }
}

Dosyayı kaydet, ardından Cursor’u yeniden başlat. Cursor Settings → Features → MCP altında sunucuların listelendiğini ve yeşil noktayla “aktif” göründüğünü doğrula.

Proje-düzeyinde MCP

Takım içinde ortak bir MCP yapılandırması kullanmak istiyorsan proje kökünde .cursor/mcp.json dosyası oluştur. Bu dosya global konfigürasyonu geçersiz kılmaz; global + proje konfigürasyonları birleşerek çalışır. Tokenler .env üzerinden enjekte edilebilir. Hassas anahtarları proje dosyasına yazma, .gitignore’a eklemeyi de unutma.

Cursor’da MCP araçlarını kullanmak için sohbet arayüzüne @ yazıp sunucu adını seç ya da doğrudan “GitHub sunucusunu kullan, son commit mesajını getir” gibi bir istek gönder. Agent modundayken Cursor, hangi sunucuyu çağıracağına kendi karar verir.

VS Code MCP (GitHub Copilot)

GitHub Copilot’un agent modu (VS Code 1.99+), MCP protokolünü destekler. Konfigürasyon için settings.json içine şunu ekle:

{
  "github.copilot.chat.experimental.mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Alternatif olarak proje kökünde .vscode/mcp.json dosyası oluşturulabilir; bu yöntem takım için paylaşımlı konfigürasyonu kolaylaştırır. VS Code’da MCP desteği hâlâ experimental etiketiyle geliyor. Kararlı bir deneyim için Cursor veya Claude Desktop’u tercih edebilirsin.

Popüler MCP Sunucuları

Resmi ve topluluk destekli MCP sunucularının kısa listesi:

Tam liste ve yeni eklenenler için modelcontextprotocol/servers reposuna bakabilirsin.

Sorun Giderme

Sunucu “aktif değil” görünüyor: Claude Desktop veya Cursor’u tamamen kapatıp açmak çoğu durumda sorunu çözer. JSON dosyasında virgül veya ayraç hatası olup olmadığını doğrula; bir JSON doğrulayıcıya yapıştırıp kontrol et.

“command not found” hatası: npx PATH’de bulunamıyor. Node.js’i doğrudan sisteme kurduğunda bu hata oluşabilir, özellikle macOS’ta nvm veya fnm üzerinden kurulduysa PATH farklı olabilir. Konfigürasyonda "command": "npx" yerine tam yolu ver:

"command": "/Users/kullanici/.nvm/versions/node/v20.0.0/bin/npx"

Tam yolu bulmak için terminalde which npx komutunu çalıştır.

API anahtarı tanınmıyor: env bloğunu doğru konuma yazdığından emin ol: mcpServers bloğunun dışında değil, ilgili sunucu nesnesinin içinde olmalı.

Log dosyaları nerede?

• macOS Claude Desktop: ~/Library/Logs/Claude/mcp*.log
• Windows Claude Desktop: %APPDATA%\Claude\logs\
• Cursor: Help → Toggle Developer Tools → Console sekmesinde MCP hataları görünür

Log çıktısını incelemek hangi sunucunun başarısız olduğunu ve neden hata verdiğini net biçimde gösterir.

Sunucu başlıyor ama araçlar görünmüyor: Claude Desktop’ta sol alt köşedeki küçük çekiç ikonuna tıkla; bağlı MCP araçlarının listesi açılır. Araç görünmüyorsa sunucu doğru başlamış ama araç tanımları aktarılamamış olabilir. Sunucu paket sürümünü güncelle:

npx -y @modelcontextprotocol/server-filesystem@latest

MCP ile RAG Karşılaştırması

RAG (Retrieval-Augmented Generation) ile MCP sık karıştırılır, ancak farklı sorunları çözerler:

Pratikte ikisi birbirini tamamlar: MCP gerçek zamanlı araç çağrısı için, RAG büyük belge koleksiyonlarını indexleyip semantik arama için kullanılır. AI agent mimarilerinde her ikisi de aynı agent pipeline’ında birlikte yer alabilir.

Kendi MCP sunucunu yazmak ve Python ile araç tanımlamak istiyorsan MCP Sunucu Nasıl Yazılır? rehberine bakabilirsin. Agentic coding araçlarıyla MCP’yi birleştirince yazılım geliştirme döngüsü ciddi ölçüde kısalıyor.

Filesystem ve GitHub sunucularıyla başlamanı öneririm. Kurulum yok, token yönetimi basit. Birkaç düzenlemeden sonra yeni sunucu eklemek dakikalık bir işe dönüşür.