OpenWeb Ninja MCP Server

OpenWeb Ninja MCP 서버

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

API 제품당 하나의 도구(41개 도구)로 각 API의 작업을 노출하며, 필요 시 API의 무료 티어를 추가하는 subscribe 도구까지 총 42개의 도구를 제공합니다. 스키마는 OpenWeb Ninja의 OpenAPI 명세에서 직접 생성되므로 서버는 항상 실제 API와 일치합니다.

설정

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

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

Claude Desktop

claude_desktop_config.json에 추가 (설정 -> 개발자 -> 구성 편집):

{
  "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). 스테이징/테스트용.

사용 가능한 도구 (42개)

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

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

채용 정보 및 기업: jsearch, job_salary_data, realtime_glassdoor_data

커머스 및 상품: 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

부동산: realtime_zillow_data, real_time_redfin_data

금융 및 이벤트: realtime_finance_data, realtime_events_data

연락처 및 정보 보강: website_contacts_scraper, email_search

유틸리티: 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의 큐레이션된 설명만 필요).