OpenWeb Ninja MCP

OpenWeb Ninja MCP 服务

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

每个 API 产品对应一个工具（共 50 个），每个工具提供该 API 的操作；另有一个 subscribe 工具，可按需添加 API 的免费套餐——总计 51 个工具。架构直接根据 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）。用于预发布环境／测试。

可用工具（51 个）

搜索与发现： 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_costco_data、real_time_wayfair_data、realtime_homedepot_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

大模型中继： 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 中精心编写的说明）。