OpenWeb Ninja MCP

OpenWeb Ninja MCP Server

OpenWeb Ninja API용 공식 Model Context Protocol 서버입니다. MCP 호환 AI 에이전트(Claude, Cursor, Cline 등)가 단일 연결을 통해 웹 검색, 지역 비즈니스 데이터, 채용 정보, 전자상거래, 부동산, 금융, 뉴스 등에 실시간으로 접근할 수 있습니다.

API 제품마다 하나의 도구(총 52개)가 제공되며, 각 도구는 해당 API의 작업을 노출합니다. 필요할 때 API의 무료 티어를 추가하는 subscribe 도구도 있어 총 53개 도구를 제공합니다. 스키마는 OpenWeb Ninja의 OpenAPI 사양에서 직접 생성되므로 서버는 항상 실제 API와 일치합니다.

설정

OpenWeb Ninja API 키가 필요합니다. openwebninja.com에서 발급받으세요.

서버는 npx을 통해 실행되므로 전역 설치가 필요하지 않습니다. 아래에서 클라이언트를 선택하세요. npx이 필요할 때 @openwebninja/mcp-server을 가져옵니다.

Claude Desktop

claude_desktop_config.json에 추가하세요(Settings -> Developer -> Edit Config).

{
  "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

클라이언트의 MCP 설정(mcp.json 또는 이에 해당하는 설정)에 동일한 command / args / env 형식을 사용하세요.

소스에서 실행(로컬 개발)

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

그런 다음 빌드된 엔트리를 사용하도록 MCP 클라이언트를 설정하세요.

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

도구 작동 방식

각 도구는 하나의 OpenWeb Ninja API에 대응하며 두 가지 입력을 받습니다.

• operation: 호출할 엔드포인트(예: search, product_details)
• args: 해당 작업의 매개변수

도구 설명에는 모든 작업과 필수 매개변수가 나열되어 있습니다. jsearch 도구 호출 예시:

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

요청을 보내기 전에 인수의 유효성을 검사하고 형식을 변환합니다. 응답에는 OpenWeb Ninja data 페이로드와 request_id가 포함됩니다.

환경 변수

변수	필수	설명
OPENWEBNINJA_API_KEY	예	OpenWeb Ninja API 키(x-api-key으로 전송됨).
OPENWEBNINJA_BASE_URL	아니요	API 호스트 재정의(기본값은 https://api.openwebninja.com). 스테이징/테스트용입니다.

사용 가능한 도구(54)

검색 및 탐색: realtime_web_search, realtime_bing_search_data, 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

지역 및 지도: local_business_data, local_business_database, yelp_business_data, trustpilot_company_and_reviews, local_rank_tracker, driving_directions, waze, google_maps_traffic_alerts, ev_charge_finder

채용 및 기업: jsearch, realtime_linkedin_data, realtime_indeed_data, realtime_ziprecruiter_data, realtime_monster_data, job_salary_data, realtime_glassdoor_data

상거래 및 제품: realtime_amazon_data, realtime_product_search, real_time_walmart_data, real_time_ebay_data, realtime_aliexpress_data, realtime_costco_data, real_time_wayfair_data, realtime_homedepot_data, realtime_lowes_data, realtime_books_data, play_store_apps

부동산: realtime_zillow_data, real_time_redfin_data

금융 및 이벤트: realtime_finance_data, realtime_events_data

연락처 및 데이터 보강: website_contacts_scraper, email_search, realtime_similarweb_data

유틸리티: web_unblocker

LLM 릴레이: chatgpt, gemini, copilot

액세스: subscribe (필요할 때 API의 무료 티어 추가)

개발

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

파이프라인은 다음과 같습니다. OpenAPI 사양(openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> 런타임에 src/server.ts에 도구 등록. API를 추가하거나 업데이트하려면 사양을 다시 동기화하고 재생성하면 됩니다. 도구별 코드를 직접 작성할 필요는 없습니다(src/lib/descriptions.ts의 엄선된 설명만 예외).