OpenWeb Ninja MCP

Servidor OpenWeb Ninja MCP

Servidor oficial del Model Context Protocol para las API de OpenWeb Ninja. Proporciona a cualquier agente de IA compatible con MCP (Claude, Cursor, Cline y otros) acceso en tiempo real a búsquedas web, datos de negocios locales, empleos, comercio electrónico, bienes raíces, finanzas, noticias y mucho más, mediante una sola conexión.

Una herramienta por producto de API (52 herramientas), cada una expone las operaciones de esa API, además de una herramienta subscribe para añadir bajo demanda el nivel gratuito de una API: 53 herramientas en total. Los esquemas se generan directamente a partir de las especificaciones OpenAPI de OpenWeb Ninja, por lo que el servidor siempre coincide con las API activas.

Configuración

Necesitas una clave de API de OpenWeb Ninja. Consigue una en openwebninja.com.

El servidor se ejecuta mediante npx; no hay que instalar nada globalmente. Elige tu cliente a continuación; npx obtiene @openwebninja/mcp-server bajo demanda.

Claude Desktop

Añádelo a 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

Usa la misma estructura de command / args / env en la configuración MCP del cliente (mcp.json o equivalente).

Desde el código fuente (desarrollo local)

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

Luego, configura tu cliente MCP para que use la entrada compilada:

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

Cómo funcionan las herramientas

Cada herramienta corresponde a una API de OpenWeb Ninja y acepta dos entradas:

• operation: qué endpoint llamar (p. ej., search, product_details)
• args: los parámetros de esa operación

La descripción de la herramienta enumera todas las operaciones y sus parámetros obligatorios. Ejemplo de llamada a la herramienta jsearch:

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

Los argumentos se validan y se convierten al tipo correspondiente antes de enviar la solicitud, y las respuestas devuelven la carga útil de OpenWeb Ninja data junto con un request_id.

Variables de entorno

Variable	Obligatoria	Descripción
OPENWEBNINJA_API_KEY	sí	Tu clave de API de OpenWeb Ninja (se envía como x-api-key).
OPENWEBNINJA_BASE_URL	no	Anula el host de la API (el valor predeterminado es https://api.openwebninja.com). Para pruebas y entornos de staging.

Herramientas disponibles (53)

Búsqueda y descubrimiento: 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 y mapas: 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

Empleos y empresas: jsearch, realtime_linkedin_data, realtime_indeed_data, realtime_ziprecruiter_data, realtime_monster_data, realtime_bing_jobs_data, job_salary_data, realtime_glassdoor_data

Comercio y productos: 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

Bienes raíces: realtime_zillow_data, real_time_redfin_data

Finanzas y eventos: realtime_finance_data, realtime_events_data

Contacto y enriquecimiento: website_contacts_scraper, email_search

Utilidad: web_unblocker

Relés LLM: chatgpt, gemini, copilot

Acceso: subscribe (añade bajo demanda el nivel gratuito de una API)

Desarrollo

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

El flujo de trabajo es: especificaciones OpenAPI (openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> herramientas registradas en tiempo de ejecución en src/server.ts. Para añadir o actualizar una API, vuelve a sincronizar las especificaciones y genera de nuevo; no hace falta escribir código manual para cada herramienta (solo las descripciones seleccionadas en src/lib/descriptions.ts).