ArXiv MCP Server

🔍 AI asistanlarının basit bir MCP arayüzü aracılığıyla arXiv makalelerini aramasını ve erişmesini sağlayın.

ArXiv MCP Server, Model Context Protocol (MCP) aracılığıyla AI asistanları ile arXiv araştırma deposu arasında bir köprü sağlar. AI modellerinin makaleleri aramasını ve içeriklerine programlı şekilde erişmesini sağlar.

✨ Temel Özellikler

• 🔎 Makale Arama: Tarih aralığı ve kategori filtreleriyle arXiv makalelerini sorgulayın
• 📄 Makale Erişimi: Makale içeriğini indirin ve okuyun
• 📋 Makale Listesi: İndirilen tüm makaleleri görüntüleyin
• 🗃️ Yerel Depolama: Makaleler daha hızlı erişim için yerel olarak kaydedilir
• 📝 İstemleri: Makale analizi için bir dizi araştırma istemi

🔒 Güvenlik

Prompt Injection Riski

arXiv'den alınan makale içeriği güvenilmeyen harici girdilerdir.

Bir AI asistanı bu sunucu aracılığıyla bir makaleyi indirdiğinde veya okuduğunda, makalenin metni doğrudan modelin bağlamına iletilir. Kötü niyetli bir makale, AI'ın davranışını ele geçirmek için tasarlanan adversarial talimatları içerebilir — örneğin, veri sızıntısı yapması, diğer araçları beklenmeyen argümanlarla çağırması veya sistem düzeyindeki talimatlara geçersiz kılması istenebilir. Bu, OWASP tarafından LLM01: Prompt Injection olarak ve OWASP Agentic AI framework'ü tarafından AG01: LLM-Entegre Sistemlerde Prompt Injection olarak tanımlanan bilinen bir saldırı sınıfıdır.

Önerilen Azaltma Yolları

1. Salt okunur MCP konfigürasyonları kullanın — mümkün olduğunda, MCP istemcisini arxiv-mcp-server'ın yazma işlemleri tetikleyemeyeceği veya diğer araçları sizin adınıza çağıramayacağı şekilde yapılandırın.
2. Makale içeriğini AI özet alımından önce gözden geçirin — bir AI özeti orijinal isteğinizin parçası olmayan komutları çalıştırmanız veya harici URL'leri ziyaret etmeniz istiyorsa, bunu kırmızı bayrak olarak değerlendirin.
3. Çoklu araç kurulumlarında dikkatli olun — bu sunucuyu dosya sistemi, shell veya tarayıcı araçlarıyla birleştiren agentic boru hatları daha yüksek risklidir; bir makaledeki prompt injection, araç çağrılarını beklenmedik şekilde zincirleyebilir.
4. AI tarafından oluşturulan özetleri talimat değil veri olarak değerlendirin — AI'ın bir makaleyi okuduktan sonra önerdiği herhangi bir eylemi yürütmeden önce her zaman insan yargısı uygulayın.

Referanslar

• OWASP LLM01: Prompt Injection
• OWASP Agentic AI - AG01: Prompt Injection

---

🚀 Hızlı Başlangıç

Smithery Aracılığıyla Kurulum

ArXiv Server'ı Claude Desktop'a Smithery aracılığıyla otomatik olarak yüklemek için:

npx -y @smithery/cli install arxiv-mcp-server --client claude

Claude Desktop Aracılığıyla Kurulum (.mcpb)

.mcpb paketi macOS üzerinde Claude Desktop için tek tıklamalı kurulum yoludur. Sunucu kodunu ve Python paket bağımlılıklarını içerir, bu nedenle kullanıcıların uv, pip veya manuel MCP JSON konfigürasyonuna ihtiyacı yoktur. Python 3.11+ yine de kullanıcının makinasında mevcut olmalıdır.

1. En son sürümden Mac'inize uygun yapıyı indirin:
   • Apple Silicon: arxiv-mcp-server-darwin-arm64-<version>.mcpb
   • Intel: arxiv-mcp-server-darwin-x86_64-<version>.mcpb
2. Claude Desktop'ta Ayarlar → Uzantılar'ı açın (veya dosyayı Claude Desktop penceresine sürükleyip bırakın).
3. Yükle'ye tıklayın ve istendiğinde tercih ettiğiniz makale depolama dizinini ayarlayın (varsayılan: ~/.arxiv-mcp-server/papers).

Claude Desktop, yığılmış sunucuyu stdio üzerinden başlatır — konfigürasyon dosyası düzenlemesine gerek yoktur.

Elle Kurulum

Önemli — uv tool install kullanın, npm/pnpm veya uv pip install kullanmayın

Bu proje, desteklenen sunucuyu PyPI'de bir Python paketi olarak yayınlar. arxiv-mcp-server'ı npm install, pnpm add veya npx arxiv-mcp-server ile kurmayın: bu adla npm paketi, ilgisiz bir üçüncü taraf paketidir ve kendi Python algılama wrapper'ına sahiptir.

uv pip install arxiv-mcp-server çalıştırmak paketi mevcut sanal ortama yükler ancak arxiv-mcp-server yürütülebilirini PATH'e yerleştirmez. uv tool install kullanmalısınız, böylece uv izole edilmiş bir ortam oluşturur ve yürütülebilir dosyayı global olarak ortaya çıkarır:

uv tool install arxiv-mcp-server

Bundan sonra arxiv-mcp-server komutu PATH üzerinde kullanılabilir olacaktır.

PDF fallback (eski makaleler): Çoğu arXiv makalesi temel yüklemenin otomatik olarak işlediği bir HTML versiyonuna sahiptir. Yalnızca PDF'ye sahip eski makaleler için sunucu [pdf] extra'sına ihtiyaç duyar (pymupdf4llm). Bunu yükleyin:

uv tool install 'arxiv-mcp-server[pdf]'

Bunu doğrulayabilirsiniz:

arxiv-mcp-server --help

Daha önce uv pip install arxiv-mcp-server çalıştırdıysanız ve komut eksikse, kaldırın ve yukarıda gösterildiği gibi uv tool install ile yeniden yükleyin.

Geliştirme için:

# Klonlayın ve geliştirme ortamını ayarlayın
git clone https://github.com/blazickjp/arxiv-mcp-server.git
cd arxiv-mcp-server

# Sanal ortam oluşturun ve etkinleştirin
uv venv
source .venv/bin/activate

# Test bağımlılıklarıyla yükleyin (yalnızca geliştirme — global yürütülebilir yok)
uv pip install -e ".[test]"

🤖 Codex Plugin Entegrasyonu

Bu depo şu anda .codex-plugin/plugin.json konumunda bir Codex plugin manifestini ve .mcp.json konumunda taşınabilir bir MCP config'ini içerir, böylece Codex yönelimli araçlar sunucuyu kendi kurulum tarifini icat etmeden keşfedebilir.

Codex entegrasyonu, bu README'nin başka yerlerinde belgelenen aynı stdio başlatma yolunu kullanır:

{
  "mcpServers": {
    "arxiv": {
      "command": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}

Codex istemciniz plugin manifestlerini destekliyorsa, ./.codex-plugin/plugin.json'a işaret edin. Yalnızca ham MCP konfigürasyonunu destekliyorsa, ./.mcp.json'ı doğrudan kullanın.

🔌 MCP Entegrasyonu

Bu konfigürasyonu MCP istemci konfigürasyon dosyanıza ekleyin:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "command": "uv",
            "args": [
                "tool",
                "run",
                "arxiv-mcp-server",
                "--storage-path", "/path/to/paper/storage"
            ]
        }
    }
}

Geliştirme için:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "path/to/cloned/arxiv-mcp-server",
                "run",
                "arxiv-mcp-server",
                "--storage-path", "/path/to/paper/storage"
            ]
        }
    }
}

HTTP Aktarımı

Stdio'nun pratik olmadığı sunucu dağıtımları için, sunucuyu Streamable HTTP ile çalıştırın:

TRANSPORT=http HOST=127.0.0.1 PORT=8080 arxiv-mcp-server --storage-path /path/to/papers

Ardından Streamable HTTP'yi destekleyen bir MCP istemcisini yapılandırın:

{
    "mcpServers": {
        "arxiv-mcp-server": {
            "type": "http",
            "url": "http://127.0.0.1:8080/mcp"
        }
    }
}

Varsayılan HTTP bağlama adresi 127.0.0.1'dir. Streamable HTTP, MCP DNS rebinding korumasını varsayılan olarak etkinleştirir ve yapılandırılmış port için localhost adreslerine izin verir. Sunucuyu bir ters proxy aracılığıyla açığa çıkartıyorsanız, hızlandırıcının üzerinde kimlik doğrulaması ve ağ denetimleri eklemiş olmadığınız sürece localhost'a bağlı tutun; ALLOWED_HOSTS ve ALLOWED_ORIGINS'i proxy'nizin ilettiği harici host/origin değerlerine ayarlayın.

🔒 Güvenlik Notu

arXiv makaleleri kullanıcı tarafından oluşturulmuş, güvenilmeyen içeriktir. Bu sunucu tarafından döndürülen makale metni prompt injection denemelerini içerebilir — bir AI asistanının davranışını manipüle etmek için tasarlanmış metin. Tüm makale içeriğini güvenilmeyen girdiye olarak değerlendirin.

Üretim ortamlarında uygun sandboxing uygulayın ve ham makale içeriğini duyarlı araçlara veya verilere erişimi olan agentic boru hatlarına incelemesi olmadan beslemekten kaçının. Tam güvenlik politikası için SECURITY.md'ye bakın.

💡 Mevcut Araçlar

Temel İş Akışı

Derin makale araştırması için tipik iş akışı:

search_papers → download_paper → read_paper

list_papers yerel olarak neye sahip olduğunuzu gösterir. semantic_search yerel koleksiyon genelinde arama yapar.

---

1. Makale Arama

Opsiyonel kategori, tarih ve boolean filtrelerine sahip arXiv'i arayın. arXiv'in 3 saniyelik hız sınırını otomatik olarak uygular. Hız sınırlanıyorsa, yeniden denemeden önce 60 saniye bekleyin.

result = await call_tool("search_papers", {
    "query": "\"KAN\" OR \"Kolmogorov-Arnold Networks\"",
    "max_results": 10,
    "date_from": "2024-01-01",
    "categories": ["cs.LG", "cs.AI"],
    "sort_by": "date"   # or "relevance" (default)
})

Desteklenen kategoriler cs.AI, cs.LG, cs.CL, cs.CV, cs.NE, stat.ML, math.OC, quant-ph, eess.SP ve daha fazlasını içerir. Tam liste için araç açıklamasına bakın.

2. Makale İndirme

Bir makaleyi arXiv ID'sine göre indirin. İlk olarak HTML'yi dener, PDF'ye geri döner. Makaleyi read_paper ve semantic_search için yerel olarak depolar. Yanıt, istemcilerin çok büyük makaleleri istemci tarafı çıktı sınırını başarısız bir indirme ile karıştırmadan güvenli bir şekilde sayfalandırabilmesi için content_length, returned_chars, next_start ve is_truncated içerir.

result = await call_tool("download_paper", {
    "paper_id": "2401.12345"
})

# For very large papers, request bounded chunks:
result = await call_tool("download_paper", {
    "paper_id": "2401.12345",
    "start": 0,
    "max_chars": 50000
})

Yalnızca PDF'ye sahip eski makaleler için [pdf] extra'sını yükleyin: uv tool install 'arxiv-mcp-server[pdf]'

3. Makaleleri Listele

Yerel olarak indirilen tüm makaleleri listeleyin. Yalnızca arXiv ID'lerini döndürür — içeriğe erişmek için read_paper kullanın.

result = await call_tool("list_papers", {})

4. Makale Oku

Yerel olarak indirilen bir makalenin tam metnini markdown'da okuyun. download_paper'ın ilk olarak çağrılması gerekir. Büyük makaleleri sayfalandırmak için start ve max_chars ile döndürülen next_start değerini kullanın.

result = await call_tool("read_paper", {
    "paper_id": "2401.12345"
})

result = await call_tool("read_paper", {
    "paper_id": "2401.12345",
    "start": 50000,
    "max_chars": 50000
})

📝 Araştırma İstemleri

Sunucu akademik makaleleri analiz etmeye yardımcı olmak için özel istlemler sağlar:

Makale Analiz İstemi

Yalnızca bir makale ID'si gerektiren akademik makaleleri analiz etmek için kapsamlı bir iş akışı:

result = await call_prompt("deep-paper-analysis", {
    "paper_id": "2401.12345"
})

Bu istlem şunları içerir:

• Mevcut araçları (list_papers, download_paper, read_paper, search_papers) kullanmak için detaylı talimatlar
• Makale analizi için sistematik iş akışı
• Kapsamlı analiz yapısı kapsam:
  • Yönetici özeti
  • Araştırma bağlamı
  • Metodoloji analizi
  • Sonuçlar değerlendirmesi
  • Pratik ve teorik çıkarımlar
• Gelecek araştırma yönelimleri
• Daha geniş etkiler

Pro İstlem Paketi

• summarize_paper: bir makale için özlü yapılandırılmış özet.
• compare_papers: makale ID'leri arasında yan yana teknik karşılaştırma.
• literature_review: bir konu ve opsiyonel makale seti genelinde tematik sentez.

⚙️ Konfigürasyon

Komut satırı seçenekleri ve ortam değişkenleri aracılığıyla yapılandırın:

Ayar	Amaç	Varsayılan
--storage-path	Makale depolama konumu	~/.arxiv-mcp-server/papers
MAX_RESULTS	Maksimum arama sonuçları	50
REQUEST_TIMEOUT	API zaman aşımı (saniye cinsinden)	60
TRANSPORT	Aktarım türü: stdio, http veya streamable-http	stdio
HOST	HTTP modunda bağlanacak host	127.0.0.1
PORT	HTTP modunda dinlenecek port	8000
ALLOWED_HOSTS	Streamable HTTP DNS rebinding koruması için virgülle ayrılmış ekstra izin verilen Host header değerleri	boş
ALLOWED_ORIGINS	Streamable HTTP DNS rebinding koruması için virgülle ayrılmış ekstra izin verilen Origin header değerleri	boş

🧪 Test Etme

Test paketini çalıştırın:

python -m pytest

🧪 Deneysel Özellikler

Bu özellikler henüz tam olarak test edilmemiştir ve beklenmedik davranışlar gösterebilir. Dikkatli kullanın.

Aşağıdaki araçlar ek bağımlılıklar gerektirip aktif geliştirme aşamasındadır:

uv pip install -e ".[pro]"

Anlamsal Arama

Yalnızca yerel olarak indirilen makaleleriniz üzerinde anlamsal benzerlik araması. Henüz bir makale indirilmediyse boş sonuçlar döndürür. [pro] bağımlılıklarını gerektirir.

result = await call_tool("semantic_search", {
    "query": "test-time adaptation in multimodal transformers",
    "max_results": 5
})
# or find papers similar to a known paper:
result = await call_tool("semantic_search", {
    "paper_id": "2404.19756",
    "max_results": 5
})

Atıf Grafiği

Semantic Scholar aracılığıyla referansları ve alıntı yapan makaleleri getirin. Herhangi bir arXiv ID'sinde çalışır — yerel indirmeye gerek yoktur.

result = await call_tool("citation_graph", {
    "paper_id": "2401.12345"
})

Araştırma Uyarıları

Konu izlemeleri kaydedip son kontrolden sonra yayınlanan yeni makaleler için oylamaya alın. search_papers ile aynı sorgu sözdizimini kullanır.

# Watch'i kaydedin (idempotent — tekrar çağırılması varolan watch'i günceller)
await call_tool("watch_topic", {
    "topic": "\"multi-agent reinforcement learning\"",
    "categories": ["cs.AI", "cs.LG"],
    "max_results": 10
})

# Tüm watch'leri kontrol edin — yalnızca son kontrolden sonra yayınlanan makaleleri döndürür
result = await call_tool("check_alerts", {})

# Tek bir watch'i kontrol edin
result = await call_tool("check_alerts", {"topic": "\"multi-agent reinforcement learning\""})

Gelişmiş İstlemler

Daha derin araştırma iş akışları için summarize_paper, compare_papers ve literature_review. [pro] bağımlılıklarını gerektirir.

---

📄 Lisans

Apache License 2.0 altında yayınlanmıştır. Ayrıntılar için LICENSE dosyasına bakın.

---