OpenWeb Ninja MCP

OpenWeb Ninja MCP Server

Servidor oficial do Model Context Protocol para as APIs da OpenWeb Ninja. Dá a qualquer agente de IA compatível com MCP (Claude, Cursor, Cline e outros) acesso em tempo real a pesquisas na web, dados de empresas locais, vagas de emprego, comércio eletrônico, imóveis, finanças, notícias e muito mais, por meio de uma única conexão.

Uma ferramenta por produto de API (52 ferramentas), cada uma expondo as operações dessa API, além de uma ferramenta subscribe para adicionar sob demanda o nível gratuito de uma API — 53 ferramentas no total. Os esquemas são gerados diretamente a partir das especificações OpenAPI da OpenWeb Ninja, para que o servidor sempre corresponda às APIs em produção.

Configuração

Você precisa de uma chave de API da 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 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

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 corresponde a uma API da OpenWeb Ninja e recebe duas entradas:

• operation: qual endpoint chamar (por exemplo, search, product_details)
• args: os parâmetros dessa operação

A descrição da ferramenta lista todas as operações e seus parâmetros obrigatórios. Exemplo de chamada à 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 solicitação, e as respostas retornam o conteúdo data da OpenWeb Ninja, além de um request_id.

Variáveis de ambiente

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

Ferramentas disponíveis (53)

Pesquisa e descoberta: 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 e 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

Vagas e empresas: jsearch, realtime_linkedin_data, realtime_indeed_data, realtime_ziprecruiter_data, realtime_monster_data, realtime_bing_jobs_data, 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_aliexpress_data, realtime_costco_data, real_time_wayfair_data, realtime_homedepot_data, realtime_lowes_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

Relays de LLM: chatgpt, gemini, copilot

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

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 fluxo é: especificações OpenAPI (openapi-cache/) -> scripts/generate.ts -> src/generated/manifest.ts -> ferramentas registradas em tempo de execução em src/server.ts. Para adicionar ou atualizar uma API, sincronize novamente as especificações e gere os arquivos; não é necessário escrever código manual para cada ferramenta (apenas as descrições selecionadas em src/lib/descriptions.ts).