OpenWeb Ninja MCP

OpenWeb Ninja MCP Sunucusu

Model Context Protocol için resmi OpenWeb Ninja API'leri sunucusu. MCP uyumlu herhangi bir AI aracısına (Claude, Cursor, Cline ve diğerleri) tek bir bağlantı üzerinden web araması, yerel işletme verileri, iş ilanları, e-ticaret, emlak, finans, haberler ve daha fazlasına gerçek zamanlı erişim sağlar.

Her API ürünü için bir araç (41 araç), her biri o API'nin işlemlerini sunar, ayrıca isteğe bağlı olarak bir API'nin ücretsiz katmanını eklemek için bir subscribe aracı — toplamda 42 araç. Şemalar doğrudan OpenWeb Ninja'nın OpenAPI spesifikasyonlarından oluşturulur, böylece sunucu her zaman canlı API'lerle eşleşir.

Kurulum

Bir OpenWeb Ninja API anahtarına ihtiyacınız var. openwebninja.com adresinden edinin.

Sunucu npx aracılığıyla çalışır — global olarak kurulacak bir şey yoktur. Aşağıdan istemcinizi seçin; npx isteğe bağlı olarak @openwebninja/mcp-server getirir.

Claude Desktop

claude_desktop_config.json dosyasına ekleyin (Ayarlar -> Geliştirici -> Yapılandırmayı Düzenle):

{
  "mcpServers": {
    "openwebninja": {
      "command": "npx",
      "args": ["-y", "@openwebninja/mcp-server"],
      "env": { "OPENWEBNINJA_API_KEY": "your-api-key" }
    }
  }
}

Claude Code

claude mcp add openwebninja -e OPENWEBNINJA_API_KEY=your-api-key -- npx -y @openwebninja/mcp-server

Cursor / Cline / Continue / Windsurf

İstemcinin MCP yapılandırmasında (mcp.json veya eşdeğeri) aynı command / args / env şeklini kullanın.

Kaynaktan (yerel geliştirme)

git clone <repo> && cd openwebninja-mcp
npm install
npm run build

Ardından MCP istemcinizi oluşturulan girişe yönlendirin:

{
  "mcpServers": {
    "openwebninja": {
      "command": "node",
      "args": ["/absolute/path/to/openwebninja-mcp/dist/index.js"],
      "env": { "OPENWEBNINJA_API_KEY": "your-api-key" }
    }
  }
}

Araçlar nasıl çalışır

Her araç bir OpenWeb Ninja API'sine eşlenir ve iki girdi alır:

• operation: hangi uç noktanın çağrılacağı (örn. search, product_details)
• args: o işlem için parametreler

Araç açıklaması her işlemi ve gerekli parametrelerini listeler. jsearch aracına örnek çağrı:

{
  "operation": "search",
  "args": { "query": "site reliability engineer remote", "country": "us" }
}

Argümanlar istek gönderilmeden önce doğrulanır ve tür dönüşümü yapılır, yanıtlar OpenWeb Ninja data yükü artı bir request_id döndürür.

Ortam değişkenleri

Değişken	Gerekli	Açıklama
OPENWEBNINJA_API_KEY	evet	OpenWeb Ninja API anahtarınız (x-api-key olarak gönderilir).
OPENWEBNINJA_BASE_URL	hayır	API ana bilgisayarını geçersiz kılar (varsayılan https://api.openwebninja.com). Hazırlık/test için.

Mevcut araçlar (42)

Arama & keşif: realtime_web_search, realtime_news_data, real_time_news_search, realtime_forums_search, web_search_autocomplete, realtime_image_search, reverse_image_search, realtime_lens_data, real_time_video_search, realtime_shorts_search, ai_overviews, google_ai_mode, social_links_search

Yerel & haritalar: local_business_data, yelp_business_data, trustpilot_company_and_reviews, local_rank_tracker, driving_directions, waze, ev_charge_finder

İş ilanları & şirketler: jsearch, job_salary_data, realtime_glassdoor_data

Ticaret & ürün: realtime_amazon_data, realtime_product_search, real_time_walmart_data, real_time_ebay_data, realtime_costco_data, real_time_wayfair_data, realtime_books_data, play_store_apps

Emlak: realtime_zillow_data, real_time_redfin_data

Finans & etkinlikler: realtime_finance_data, realtime_events_data

İletişim & zenginleştirme: website_contacts_scraper, email_search

Yardımcı program: web_unblocker

LLM aktarıcıları: chatgpt, gemini, copilot

Erişim: subscribe (isteğe bağlı olarak bir API'nin ücretsiz katmanını ekler)

Geliştirme

npm run sync       # sync OpenAPI specs from S3 into openapi-cache/ (needs AWS creds)
npm run generate   # regenerate src/generated/manifest.ts from the specs
npm run build      # compile TypeScript to dist/
npm run dev        # run the server over stdio (tsx, no build)
npm run inspect    # launch the MCP Inspector against the server
npx tsx test/smoke.ts   # smoke test: list tools + validation + request path

İşlem hattı şöyledir: OpenAPI spesifikasyonları (openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> araçlar çalışma zamanında src/server.ts içinde kaydedilir. Bir API eklemek veya güncellemek için spesifikasyonları yeniden senkronize edin ve yeniden oluşturun; elle yazılmış araç başına kod gerekmez (yalnızca src/lib/descriptions.ts içindeki özenle hazırlanmış açıklamalar).