OpenAI WebSearch MCP Server 🔍

OpenAI'nin reasoning modellerini kullanan akıllı web arama yetenekleri sağlayan ileri seviye bir MCP sunucusu. Güncel bilgiye ve akıllı reasoning yeteneklerine ihtiyaç duyan AI asistanları için mükemmeldir.

✨ Özellikler

• 🧠 Reasoning Model Desteği: OpenAI'nin en son reasoning modelleriyle tam uyumluluk (gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini)
• ⚡ Akıllı Çaba Kontrolü: Kullanım durumuna göre akıllı reasoning_effort varsayılanları
• 🔄 Çok Modlu Arama: gpt-5-mini ile hızlı iterasyonlar veya gpt-5 ile derin araştırma
• 🌍 Yerelleştirilmiş Sonuçlar: Konum tabanlı arama özelleştirmesi desteği
• 📝 Zengin Açıklamalar: Kolay entegrasyon için tam parametre dokumentasyonu
• 🔧 Esnek Konfigürasyon: Kolay dağıtım için environment variable desteği

🚀 Hızlı Başlangıç

Claude Desktop için Tek Tıkla Kurulum

OPENAI_API_KEY=sk-xxxx uvx --with openai-websearch-mcp openai-websearch-mcp-install

sk-xxxx yerine OpenAI Platform'dan aldığınız OpenAI API anahtarını yazın.

⚙️ Konfigürasyon

Claude Desktop

claude_desktop_config.json dosyanıza şu satırları ekleyin:

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "uvx",
      "args": ["openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
      }
    }
  }
}

Cursor

Cursor'da MCP ayarlarına şunu ekleyin:

1. Cursor Ayarlarını açın (Cmd/Ctrl + ,)
2. "MCP" araması yapın veya Extensions → MCP'ye gidin
3. Sunucu konfigürasyonunu ekleyin:

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "uvx",
      "args": ["openai-websearch-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini"
      }
    }
  }
}

Claude Code

Claude Code, Claude Desktop için yapılandırılmış MCP sunucularını otomatik olarak algılar. Claude Desktop ile aynı konfigürasyonu kullanın.

Yerel Geliştirme

Yerel test için sanal ortamınıza tam yolu kullanın:

{
  "mcpServers": {
    "openai-websearch-mcp": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "openai_websearch_mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_DEFAULT_MODEL": "gpt-5-mini",
        "PYTHONPATH": "/path/to/your/project/src"
      }
    }
  }
}

🛠️ Mevcut Araçlar

openai_web_search

Reasoning model desteğiyle akıllı web arama.

Parametreler

Parametre	Tür	Açıklama	Varsayılan
input	string	Arama sorgusu veya soru	Zorunlu
model	string	Kullanılacak AI modeli. Desteklenen: gpt-4o, gpt-4o-mini, gpt-5, gpt-5-mini, gpt-5-nano, o3, o4-mini	gpt-5-mini
reasoning_effort	string	Reasoning çaba seviyesi: low, medium, high, minimal	Akıllı varsayılan
type	string	Web arama API versiyonu	web_search_preview
search_context_size	string	Bağlam miktarı: low, medium, high	medium
user_location	object	Yerelleştirilmiş sonuçlar için isteğe bağlı konum	null

💬 Kullanım Örnekleri

Konfigürasyondan sonra, AI asistanınızdan doğal dil kullanarak bilgi aramasını isteyebilirsiniz:

Hızlı Arama

"openai_web_search kullanarak AI reasoning modellerindeki son gelişmeleri ara"

Derin Araştırma

"Kuantum bilişim atılımları hakkında kapsamlı bir analiz sunmak için openai_web_search'ü gpt-5 ve high reasoning effort ile kullan"

Yerelleştirilmiş Arama

"openai_web_search kullanarak bu hafta San Francisco'da yerel teknoloji buluşmalarını ara"

AI asistanı, isteğinize göre uygun parametrelerle openai_web_search aracını otomatik olarak kullanacaktır.

🤖 Model Seçimi Rehberi

Hızlı Çok Turlu Aramalar 🚀

• Tavsiye Edilen: gpt-5-mini ile reasoning_effort: "low"
• Kullanım Durumu: Hızlı iterasyonlar, gerçek zamanlı bilgi, çoklu hızlı sorgular
• Faydaları: Daha düşük gecikme, sık aramalar için uygun maliyetli

Derin Araştırma 🔬

• Tavsiye Edilen: gpt-5 ile reasoning_effort: "medium" veya "high"
• Kullanım Durumu: Kapsamlı analiz, karmaşık konular, detaylı araştırma
• Faydaları: Çok turlu reasoning sonuçları, agent iterasyonlarına gerek yok

Model Karşılaştırması

Model	Reasoning	Varsayılan Çaba	En İyi Kullanım
gpt-4o	❌	N/A	Standart arama
gpt-4o-mini	❌	N/A	Basit sorgular
gpt-5-mini	✅	low	Hızlı iterasyonlar
gpt-5	✅	medium	Derin araştırma
gpt-5-nano	✅	medium	Dengeli yaklaşım
o3	✅	medium	İleri reasoning
o4-mini	✅	medium	Verimli reasoning

📦 Kurulum

uvx Kullanarak (Tavsiye Edilir)

# Doğrudan kur ve çalıştır
uvx openai-websearch-mcp

# Veya global olarak kur
uvx install openai-websearch-mcp

pip Kullanarak

# PyPI'den kur
pip install openai-websearch-mcp

# Sunucuyu çalıştır
python -m openai_websearch_mcp

Kaynaktan

# Repository'i klonla
git clone https://github.com/yourusername/openai-websearch-mcp.git
cd openai-websearch-mcp

# Bağımlılıkları yükle
uv sync

# Geliştirme modunda çalıştır
uv run python -m openai_websearch_mcp

👩‍💻 Geliştirme

Geliştirme Ortamını Kur

# Klonla ve kur
git clone https://github.com/yourusername/openai-websearch-mcp.git
cd openai-websearch-mcp

# Sanal ortam oluştur ve bağımlılıkları yükle
uv sync

# Testleri çalıştır
uv run python -m pytest

# Geliştirme modunda kur
uv pip install -e .

Environment Değişkenleri

Değişken	Açıklama	Varsayılan
OPENAI_API_KEY	OpenAI API anahtarınız	Zorunlu
OPENAI_DEFAULT_MODEL	Kullanılacak varsayılan model	gpt-5-mini

🐛 Hata Ayıklama

MCP Inspector Kullanarak

# uvx kurulumları için
npx @modelcontextprotocol/inspector uvx openai-websearch-mcp

# pip kurulumları için
npx @modelcontextprotocol/inspector python -m openai_websearch_mcp

Yaygın Sorunlar

Sorun: "Unsupported parameter: 'reasoning.effort'" Çözüm: Bu, reasoning_effort parametresiyle non-reasoning modelleri (gpt-4o, gpt-4o-mini) kullanırken oluşur. Sunucu bunu otomatik olarak, reasoning parametrelerini yalnızca uyumlu modellere uygulayarak ele alır.

Sorun: "No module named 'openai_websearch_mcp'" Çözüm: Paketi doğru kurduğunuzdan ve Python yolunuzun paket konumunu içerdiğinden emin olun.

📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakın.

🙏 Teşekkürler

• 🤖 Claude Code ile oluşturulmuştur
• 🔥 OpenAI'nin Web Search API'si tarafından desteklenmektedir
• 🛠️ Model Context Protocol üzerine inşa edilmiştir

---

Co-Authored-By: Claude noreply@anthropic.com