OpenWeb Ninja MCP

OpenWeb Ninja MCP Server

适用于 OpenWeb Ninja API 的官方 Model Context Protocol 服务器。通过单一连接，让任何兼容 MCP 的 AI 代理（Claude、Cursor、Cline 等）实时访问网页搜索、本地商家数据、职位、电商、房地产、金融、新闻等内容。

每个 API 产品对应一个工具（共 52 个），每个工具提供该 API 的各项操作；此外还有一个 subscribe 工具，可按需添加 API 的免费套餐，总计 53 个工具。Schema 直接根据 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 配置中使用相同的 command / args / env 结构（mcp.json 或同等配置）。

从源代码构建（本地开发）

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）。用于预发布环境/测试。

可用工具（53 个）

搜索与发现： 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、realtime_bing_jobs_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

实用工具： 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 中精选的说明）。