io.github.OpenWeb-Ninja/openwebninja-mcp

OpenWeb Ninja MCP Server

Official Model Context Protocol server for OpenWeb Ninja APIs. Gives any MCP-compatible AI agent (Claude, Cursor, Cline, and others) real-time access to web search, local business data, jobs, e-commerce, real estate, finance, news, and more, through a single connection.

One tool per API product (50 tools), each exposing that API's operations, plus a subscribe tool for adding an API's free tier on demand — 51 tools in total. Schemas are generated directly from OpenWeb Ninja's OpenAPI specs, so the server always matches the live APIs.

Setup

You need an OpenWeb Ninja API key. Get one at openwebninja.com.

The server runs via npx — there's nothing to install globally. Pick your client below; npx fetches @openwebninja/mcp-server on demand.

Claude Desktop

Add to 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

Use the same command / args / env shape in the client's MCP config (mcp.json or equivalent).

From source (local development)

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

Then point your MCP client at the built entry:

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

How the tools work

Each tool maps to one OpenWeb Ninja API and takes two inputs:

• operation: which endpoint to call (e.g. search, product_details)
• args: the parameters for that operation

The tool description lists every operation and its required parameters. Example call to the jsearch tool:

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

Arguments are validated and type-coerced before the request is sent, and responses return the OpenWeb Ninja data payload plus a request_id.

Environment variables

Available tools (51)

Search & discovery: 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 & maps: 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

Jobs & companies: jsearch, realtime_linkedin_data, realtime_indeed_data, realtime_ziprecruiter_data, realtime_monster_data, realtime_bing_jobs_data, job_salary_data, realtime_glassdoor_data

Commerce & product: realtime_amazon_data, realtime_product_search, real_time_walmart_data, real_time_ebay_data, realtime_costco_data, real_time_wayfair_data, realtime_homedepot_data, realtime_books_data, play_store_apps

Real estate: realtime_zillow_data, real_time_redfin_data

Finance & events: realtime_finance_data, realtime_events_data

Contact & enrichment: website_contacts_scraper, email_search

Utility: web_unblocker

LLM relays: chatgpt, gemini, copilot

Access: subscribe (add an API's free tier on demand)

Development

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

The pipeline is: OpenAPI specs (openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> tools registered at runtime in src/server.ts. To add or update an API, re-sync the specs and regenerate; no hand-written per-tool code is needed (only the curated descriptions in src/lib/descriptions.ts).