OpenWeb Ninja MCP

Servidor MCP OpenWeb Ninja

Servidor oficial do Model Context Protocol para as APIs do OpenWeb Ninja. Fornece a qualquer agente de IA compatível com MCP (Claude, Cursor, Cline e outros) acesso em tempo real a buscas na web, dados de negócios locais, empregos, e-commerce, imóveis, finanças, notícias e muito mais, através de uma única conexão.

Uma ferramenta por produto de API (41 ferramentas), cada uma expondo as operações daquela API, além de uma ferramenta subscribe para adicionar o nível gratuito de uma API sob demanda — 42 ferramentas no total. Os esquemas são gerados diretamente das especificações OpenAPI do OpenWeb Ninja, então o servidor sempre corresponde às APIs em produção.

Configuração

Você precisa de uma chave de API do OpenWeb Ninja. Obtenha uma em openwebninja.com.

O servidor é executado via npx — não há nada para instalar globalmente. Escolha seu cliente abaixo; npx busca @openwebninja/mcp-server sob demanda.

Claude Desktop

Adicione ao claude_desktop_config.json (Configurações -> Desenvolvedor -> Editar Configuração):

{
  "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 o mesmo formato command / args / env na configuração MCP do cliente (mcp.json ou equivalente).

A partir do código-fonte (desenvolvimento local)

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

Em seguida, aponte seu cliente MCP para o ponto de entrada compilado:

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

Como as ferramentas funcionam

Cada ferramenta mapeia para uma API do OpenWeb Ninja e recebe duas entradas:

• operation: qual endpoint chamar (ex.: search, product_details)
• args: os parâmetros para essa operação

A descrição da ferramenta lista cada operação e seus parâmetros obrigatórios. Exemplo de chamada para a ferramenta jsearch:

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

Os argumentos são validados e têm seus tipos convertidos antes do envio da requisição, e as respostas retornam o payload data do OpenWeb Ninja mais um request_id.

Variáveis de ambiente

Variável	Obrigatória	Descrição
OPENWEBNINJA_API_KEY	sim	Sua chave de API do OpenWeb Ninja (enviada como x-api-key).
OPENWEBNINJA_BASE_URL	não	Substitui o host da API (padrão é https://api.openwebninja.com). Para staging/testes.

Ferramentas disponíveis (42)

Busca e descoberta: 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 e mapas: local_business_data, yelp_business_data, trustpilot_company_and_reviews, local_rank_tracker, driving_directions, waze, ev_charge_finder

Empregos e empresas: jsearch, job_salary_data, realtime_glassdoor_data

Comércio e produtos: 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

Imóveis: realtime_zillow_data, real_time_redfin_data

Finanças e eventos: realtime_finance_data, realtime_events_data

Contato e enriquecimento: website_contacts_scraper, email_search

Utilitário: web_unblocker

Retransmissores LLM: chatgpt, gemini, copilot

Acesso: subscribe (adiciona o nível gratuito de uma API sob demanda)

Desenvolvimento

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

O pipeline é: especificações OpenAPI (openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> ferramentas registradas em tempo de execução no src/server.ts. Para adicionar ou atualizar uma API, ressincronize as especificações e regenere; nenhum código manual por ferramenta é necessário (apenas as descrições curadas em src/lib/descriptions.ts).