MarkItDown ile PDF'lerini Claude'a kotanı harcamadan okut

Neden PDF yerine markdown #

Claude'a bir PDF yüklediğinde her sayfa iki kez işleniyor: bir kez metin, bir kez görüntü olarak. Anthropic'in dokümantasyonuna göre bir sayfanın yalnızca metni 1.500 ile 3.000 token arasında tutuyor; sayfanın görüntüsü bunun üstüne ayrıca sayılıyor. Ders notu ya da sözleşme gibi yazı ağırlıklı bir dosyada görüntü, metne neredeyse hiçbir şey eklemiyor.

MarkItDown, Microsoft'un dosyaları markdown'a çeviren ücretsiz ve açık kaynaklı aracı. PDF, Word, Excel, PowerPoint ve EPUB dosyalarını, web sayfalarını ve YouTube linklerini metne çevirirken başlıkları, listeleri ve tabloları koruyor. Claude'a da bu metin gidiyor. GitHub'da 185 binden fazla yıldızı var.

Grafik ve görsel ağırlıklı dosyaları PDF olarak yüklemeye devam et. MarkItDown görselleri okumuyor; grafiklerde ve görsellerde anlatılan her şey çeviride kayboluyor.

Başlamadan önce #

• Claude Desktop: MarkItDown'ı Claude'a masaüstü uygulaması üzerinden bağlayacaksın; tarayıcıdaki Claude'da bu kurulum çalışmıyor.
• Terminal: Mac'te Terminal, Windows'ta PowerShell. Yazacağın bütün komutlar aşağıda, kopyala düğmesiyle.
• Python gerekmiyor: Birazdan kuracağın uv, MarkItDown'a gereken Python sürümünü kendisi indiriyor.

1. uv'yi kur #

uv, Python ile yazılmış araçları kurup çalıştıran küçük bir program; MarkItDown'ı Claude'a bunun üzerinden bağlayacaksın. Terminali açıp işletim sistemine uygun komutu yapıştır:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Kurulum bitince terminali kapatıp yeniden aç; açmazsan terminal uvx komutunu tanımıyor.

2. MarkItDown'ı bir kez çalıştır #

Claude'a bağlamadan önce aracı bir kez terminalden çalıştır. uv ilk seferde MarkItDown'ı ve PDF, Word, Excel için gereken paketleri indiriyor; bu bir iki dakika sürebiliyor. İndirmeyi şimdi bitirirsen Claude Desktop ilk açılışta onu beklemek zorunda kalmıyor.

uvx markitdown-mcp

Ekranda hata yazmadan duruyorsa sorun yok: MarkItDown çalışıyor ve Claude'un bağlanmasını bekliyor. Kapatmak için Ctrl+C'ye bas.

3. uvx'in tam yolunu kopyala #

Claude Desktop, terminalin programları aradığı klasörleri her zaman bilmiyor. Ayar dosyasına uvx yerine tam yolunu yazarsan spawn uvx ENOENT gibi hatalarla uğraşmazsın. Terminalde işletim sistemine uygun komutu çalıştır:

which uvx

where.exe uvx

Mac'te çıkan satır genelde /Users/kullanici-adin/.local/bin/uvx, Windows'ta C:\Users\kullanici-adin\.local\bin\uvx.exe gibi oluyor. Bu satırı kopyala; bir sonraki adımda lazım.

4. Claude Desktop'a bağla #

Claude Desktop'ı aç, Settings → Developer sayfasına gir ve Edit Config'e tıkla. Açılan klasördeki claude_desktop_config.json dosyasını bir metin düzenleyiciyle açıp aşağıdaki metni yapıştır; command satırına bir önceki adımda kopyaladığın yolu yaz:

{
  "mcpServers": {
    "markitdown": {
      "command": "/Users/kullanici-adin/.local/bin/uvx",
      "args": ["markitdown-mcp"]
    }
  }
}

Windows'ta yoldaki her \ işaretini iki kez yaz: C:\\Users\\kullanici-adin\\.local\\bin\\uvx.exe. JSON tek ters eğik çizgiyi kabul etmiyor.

Dosyada başka sunucular varsa ikinci bir mcpServers açma. "markitdown": { … } kısmını mevcut listenin içine ekle ve aradaki virgülü unutma.

Dosyayı kaydet, Claude Desktop'tan tamamen çık ve yeniden aç. Pencereyi kapatmak yetmiyor: Mac'te Cmd+Q'ya bas, Windows'ta sistem tepsisindeki Claude simgesine sağ tıklayıp Quit'i seç.

Settings → Developer sayfasını bulamazsan dosya şurada: Mac'te ~/Library/Application Support/Claude/claude_desktop_config.json, Windows'ta %APPDATA%\Claude\claude_desktop_config.json.

5. Bağlantıyı kontrol et #

Yeni bir sohbet açıp mesaj kutusundaki araçlar menüsüne bak; listede markitdown varsa bağlantı tamam. Yoksa Settings → Developer sayfasında sunucunun yanında bir hata yazıyordur. Sebep çoğu zaman ya yanlış kopyalanmış uvx yolu ya da JSON'da unutulmuş bir virgül.

6. Dosyanın yerini söyle #

Bundan sonra dosyayı sohbete yüklemiyorsun; Claude'a bilgisayarındaki yerini söylüyorsun. MarkItDown dosyayı arka planda markdown'a çeviriyor, Claude da bu metni okuyor.

/Users/kullanici-adin/Downloads/ders-notu.pdf dosyasını markitdown ile oku ve 10 maddede özetle.

Dosyanın tam yolunu kopyalamak için Mac'te Finder'da dosyayı seçip Option+Cmd+C'ye bas. Windows'ta dosyaya sağ tıklayıp Yol olarak kopyala'yı seç.

Claude aracı ilk kez kullanırken senden onay isteyebilir. Her seferinde sormasın istiyorsan Always allow'u seç.

Word, Excel ve PowerPoint dosyalarında da aynı şekilde çalışıyor. Bir web sayfası ya da YouTube videosu için linki vermen yetiyor; videonun altyazısı varsa MarkItDown transkriptini çıkarıyor.

Bu videonun transkriptini markitdown ile çıkar ve ana fikirlerini yaz: https://www.youtube.com/watch?v=…

Claude olmadan, terminalden çevirmek #

Dosyayı bir kez çevirip başka bir yerde kullanacaksan MarkItDown'ı doğrudan terminalden de çalıştırabilirsin. Bu komutlar İndirilenler klasöründeki ders-notu.pdf dosyasını çevirip ders-notu.md adıyla aynı klasöre kaydediyor:

cd ~/Downloads
uvx --from 'markitdown[all]' markitdown ders-notu.pdf -o ders-notu.md

Çıkan .md dosyasını Claude'a, ChatGPT'ye ya da kullandığın başka bir modele yükleyebilirsin.

Daha güvenli kurulum: Docker #

Yukarıdaki kurulumda MarkItDown, bilgisayarında senin açabildiğin her dosyayı okuyabiliyor. Microsoft, Claude Desktop için aracı Docker içinde çalıştırmayı öneriyor; böylece MarkItDown yalnızca senin seçtiğin klasörü görüyor. Bunun için bilgisayarında Docker Desktop ve Git kurulu olmalı.

Önce MarkItDown'ın Docker imajını oluştur:

git clone https://github.com/microsoft/markitdown.git
cd markitdown/packages/markitdown-mcp
docker build -t markitdown-mcp:latest .

Sonra ayar dosyasındaki markitdown kısmını aşağıdakiyle değiştir. /Users/kullanici-adin/Documents/claude yerine Claude'un okumasını istediğin klasörü yaz:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/Users/kullanici-adin/Documents/claude:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

Bu klasördeki dosyalar MarkItDown'a /workdir altında görünüyor: ders-notu.pdf dosyasını okutmak için Claude'a /workdir/ders-notu.pdf yolunu ver. Claude Desktop docker komutunu bulamazsa tam yolunu which docker (Windows'ta where.exe docker) ile bulup command satırına onu yaz.

Kaynaklar #

• microsoft/markitdown: aracın GitHub sayfası
• markitdown-mcp: Claude Desktop bağlantısı ve Docker kurulumu
• uv kurulumu
• Anthropic: PDF desteği ve sayfa başına token
• Claude Desktop'a yerel MCP sunucusu bağlamak