Olostep MCP Server

Um servidor para raspagem web, pesquisas no Google e consultas de URLs de sites usando a API Olostep.

GitHub
23
Experimente este MCPPatrocinado

Documentação

Olostep MCP Server

Docker Hub npm version Licença: ISC

Uma implementação de servidor Model Context Protocol (MCP) que se integra ao Olostep para raspagem de sites, extração de conteúdo e recursos de busca. Para configurar o Olostep MCP Server, você precisa ter uma chave de API. Você pode obter a chave de API cadastrando-se no site da Olostep.

Recursos

  • Raspe conteúdo de sites em HTML, Markdown, JSON ou Texto Simples (com parsers opcionais)
  • Busca na web baseada em parser com resultados estruturados
  • Respostas de IA com citações e saídas opcionais em formato JSON
  • Raspagem em lote de até 10 mil URLs
  • Rastreamento autônomo de sites a partir de uma URL inicial
  • Descoberta e mapeamento de URLs de sites (com filtros de inclusão/exclusão)
  • Roteamento de requisições por país para conteúdo geograficamente direcionado
  • Tempos de espera configuráveis para sites com muito JavaScript
  • Tratamento e relatório abrangentes de erros
  • Configuração simples de chave de API

Instalação

Existem várias maneiras de se conectar ao Olostep MCP Server. Escolha a que melhor se adequa ao seu fluxo de trabalho.

☁️ Endpoint Remoto (Recomendado)

A maneira mais simples — sem necessidade de instalação local. Conecte-se diretamente ao nosso servidor MCP hospedado:

https://mcp.olostep.com/mcp

A autenticação é feita por meio de um token Bearer no cabeçalho Authorization usando sua chave de API da Olostep. Consulte a seção Configuração do Cliente abaixo para exemplos de configuração.

🐳 Docker Hub

Baixe e execute a imagem oficial do Docker:

docker pull olostep/mcp-server

docker run -i --rm \
  -e OLOSTEP_API_KEY="your-api-key" \
  olostep/mcp-server

🔧 Build Docker Local

Se preferir criar a imagem você mesmo a partir do código-fonte:

git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server
npm install
npm run build
docker build -t olostep/mcp-server:local .

docker run -i --rm -e OLOSTEP_API_KEY="your-api-key" olostep/mcp-server:local

📦 npx

Execute sem qualquer instalação usando npx:

env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

No Windows (PowerShell):

$env:OLOSTEP_API_KEY = "your-api-key"; npx -y olostep-mcp

No Windows (CMD):

set OLOSTEP_API_KEY=your-api-key && npx -y olostep-mcp

Ou instale globalmente:

npm install -g olostep-mcp

Configuração do Cliente

Cursor

A maneira mais fácil é usar o endpoint remoto. Crie ou edite o .cursor/mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local): Vá para Configurações do Cursor > Recursos > Servidores MCP, clique em "+ Adicionar Novo Servidor MCP":

  • Nome: olostep
  • Tipo: command
  • Comando: env OLOSTEP_API_KEY=your-api-key npx -y olostep-mcp

Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (Docker):

{
  "mcpServers": {
    "olostep": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OLOSTEP_API_KEY=YOUR_API_KEY_HERE",
        "olostep/mcp-server"
      ]
    }
  }
}

Ou instale via a CLI Smithery no terminal do seu dispositivo:

npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude

Claude Code

Adicione o endpoint remoto à sua configuração MCP do Claude Code:

{
  "mcpServers": {
    "olostep": {
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "mcpServers": {
    "olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Windsurf

Adicione isto ao seu ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "olostep": {
      "serverUrl": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "mcpServers": {
    "mcp-server-olostep": {
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

VS Code

Adicione isto ao seu .vscode/mcp.json:

{
  "servers": {
    "olostep": {
      "type": "http",
      "url": "https://mcp.olostep.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternativa (local):

{
  "servers": {
    "olostep": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "olostep-mcp"],
      "env": {
        "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Metorial

Opção 1: Instalação com Um Clique (Recomendada)

  1. Abra o painel do Metorial
  2. Navegue até o diretório de Servidores MCP
  3. Pesquise por "Olostep"
  4. Clique em "Instalar" e insira sua chave de API

Opção 2: Configuração Manual

Adicione isto à sua configuração de servidor MCP do Metorial:

{
  "olostep": {
    "command": "npx",
    "args": ["-y", "olostep-mcp"],
    "env": {
      "OLOSTEP_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}

As ferramentas da Olostep estarão então disponíveis nos seus chats de IA do Metorial.

Configuração

Variáveis de Ambiente

  • OLOSTEP_API_KEY: Sua chave de API da Olostep (obrigatória)
  • ORBIT_KEY: Uma chave opcional para usar o Orbit no roteamento de requisições.

Ferramentas Disponíveis

1. Raspar Site (scrape_website)

Extraia conteúdo de uma única URL. Suporta múltiplos formatos e renderização de JavaScript.

{
  "name": "scrape_website",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 1000,
    "parser": "@olostep/amazon-product"
  }
}

Parâmetros:

  • url_to_scrape: A URL do site que você deseja raspar (obrigatória)
  • output_format: Escolha o formato (html, markdown, json ou text) - padrão: markdown
  • country: Código de país opcional (ex.: US, GB, CA) para raspagem específica de localização
  • wait_before_scraping: Tempo de espera em milissegundos antes da raspagem (0-10000)
  • parser: ID de parser opcional para extração especializada

Resposta (exemplo):

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"id\": \"scrp_...\",\n  \"url\": \"https://example.com\",\n  \"markdown_content\": \"# ...\",\n  \"html_content\": null,\n  \"json_content\": null,\n  \"text_content\": null,\n  \"status\": \"succeeded\",\n  \"timestamp\": \"2025-11-14T12:34:56Z\",\n  \"screenshot_hosted_url\": null,\n  \"page_metadata\": { }\n}"
    }
  ]
}

2. Buscar na Web (search_web)

Busque na Web por uma consulta específica e obtenha resultados estruturados (sem IA, baseados em parser).

{
  "name": "search_web",
  "arguments": {
    "query": "your search query",
    "country": "US"
  }
}

Parâmetros:

  • query: Consulta de busca (obrigatória)
  • country: Código de país opcional para resultados localizados (padrão: US)

Resposta:

  • JSON estruturado (como texto) representando resultados baseados em parser

3. Respostas (IA) (answers)

Busque na web e retorne respostas com tecnologia de IA na estrutura JSON que você desejar, com fontes e citações.

{
  "name": "answers",
  "arguments": {
    "task": "Who are the top 5 competitors to Acme Inc. in the EU?",
    "json": "Return a list of the top 5 competitors with name and homepage URL"
  }
}

Parâmetros:

  • task: Pergunta ou tarefa a ser respondida usando dados da web (obrigatória)
  • json: Esquema/objeto JSON opcional ou uma breve descrição do formato de saída desejado

A resposta inclui:

  • answer_id, object, task, result (JSON se fornecido), sources, created

4. Raspagem em Lote de URLs (batch_scrape_urls)

Raspe até 10 mil URLs ao mesmo tempo. Perfeito para extração de dados em grande escala.

{
  "name": "batch_scrape_urls",
  "arguments": {
    "urls_to_scrape": [
      {"url": "https://example.com/a", "custom_id": "a"},
      {"url": "https://example.com/b", "custom_id": "b"}
    ],
    "output_format": "markdown",
    "country": "US",
    "wait_before_scraping": 500,
    "parser": "@olostep/amazon-product"
  }
}

A resposta inclui:

  • batch_id, status, total_urls, created_at, formats, country, parser, urls

5. Criar Rastreamento (create_crawl)

Inicie um rastreamento assíncrono que descobre e raspa sites inteiros de forma autônoma, seguindo links. Retorna um crawl_id — o rastreamento é executado em segundo plano e não retorna conteúdo nesta resposta. Você deve então chamar get_crawl_results com o crawl_id para consultar o status e recuperar as páginas raspadas (mesmo padrão de duas etapas de batch_scrape_urls + get_batch_results).

{
  "name": "create_crawl",
  "arguments": {
    "start_url": "https://example.com/docs",
    "max_pages": 25,
    "output_format": "markdown",
    "country": "US",
    "parser": "@olostep/doc-parser"
  }
}

A resposta inclui:

  • crawl_id, object, status, start_url, max_pages, created, formats, country, parser

Combine esta chamada com get_crawl_results — não passe um crawl_id para get_batch_results (rastreamentos e lotes são recursos separados).

6. Criar Mapa (create_map)

Obtenha todas as URLs de um site. Extraia todas as URLs para descoberta e análise.

{
  "name": "create_map",
  "arguments": {
    "website_url": "https://example.com",
    "search_query": "blog",
    "top_n": 200,
    "include_url_patterns": ["/blog/**"],
    "exclude_url_patterns": ["/admin/**"]
  }
}

A resposta inclui:

  • map_id, object, url, total_urls, urls, search_query, top_n

7. Obter Conteúdo de Página Web (get_webpage_content)

Recupera o conteúdo de páginas web em formato markdown limpo, com suporte à renderização de JavaScript.

{
  "name": "get_webpage_content",
  "arguments": {
    "url_to_scrape": "https://example.com",
    "wait_before_scraping": 1000,
    "country": "US"
  }
}

Parâmetros:

  • url_to_scrape: A URL da página web a ser raspada (obrigatória)
  • wait_before_scraping: Tempo de espera em milissegundos antes de iniciar a raspagem (padrão: 0)
  • country: País residencial de onde carregar a requisição (ex.: US, CA, GB) (opcional)

Resposta:

{
  "content": [
    {
      "type": "text",
      "text": "# Example Website\n\nThis is the markdown content of the webpage..."
    }
  ]
}

8. Obter URLs do Site (get_website_urls)

Busque e recupere URLs relevantes de um site, ordenadas por relevância para sua consulta.

{
  "name": "get_website_urls",
  "arguments": {
    "url": "https://example.com",
    "search_query": "your search term"
  }
}

Parâmetros:

  • url: A URL do site a ser mapeado (obrigatória)
  • search_query: A consulta de busca pela qual as URLs devem ser ordenadas (obrigatória)

Resposta:

{
  "content": [
    {
      "type": "text",
      "text": "Found 42 URLs matching your query:\n\nhttps://example.com/page1\nhttps://example.com/page2\n..."
    }
  ]
}

9. Obter Resultados do Lote (get_batch_results)

Recupere os resultados de um trabalho de raspagem em lote enviado anteriormente usando seu batch_id.

{
  "name": "get_batch_results",
  "arguments": {
    "batch_id": "batch_abc123"
  }
}

Parâmetros:

  • batch_id: O ID do lote retornado por batch_scrape_urls (obrigatório)

A resposta inclui:

  • batch_id, status (processing ou completed), total_urls, completed_urls, items (array de resultados raspados por URL com url, custom_id, markdown_content, html_content, json_content, text_content, status, page_metadata)

10. Obter Resultados do Rastreamento (get_crawl_results)

Recupere o status e as páginas raspadas de um rastreamento assíncrono iniciado com create_crawl. Esta é a ferramenta complementar obrigatória de create_crawl — create_crawl apenas inicia o trabalho e retorna um crawl_id; esta ferramenta é como você realmente obtém as páginas descobertas e seu conteúdo.

{
  "name": "get_crawl_results",
  "arguments": {
    "crawl_id": "crawl_abc123",
    "formats": ["markdown"],
    "items_limit": 20,
    "cursor": 0
  }
}

Parâmetros:

  • crawl_id: O ID do rastreamento retornado por create_crawl (obrigatório)
  • formats: Array de formatos a recuperar por página — markdown, html, json, text (padrão: ["markdown"])
  • items_limit: Máximo de páginas para recuperar conteúdo, 1–100 (padrão: 20)
  • cursor: Cursor de paginação na lista de páginas descobertas (padrão: 0)
  • search_query: Filtro opcional para classificar/selecionar páginas por relevância a uma consulta

A resposta inclui:

  • Em andamento: crawl_id, status (in_progress), pages_completed, pages_total e um message solicitando que você chame novamente em ~10 segundos.
  • Quando concluído: crawl_id, status (completed), pages_returned, next_cursor, has_more e um array pages onde cada entrada tem url, custom_id e os campos de conteúdo solicitados (markdown_content, html_content, json_content, text_content).

Tratamento de Erros

O servidor fornece tratamento robusto de erros:

  • Mensagens de erro detalhadas para problemas de API
  • Relatório de erros de rede
  • Tratamento de falhas de autenticação
  • Informações sobre limite de taxa

Exemplo de resposta de erro:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Olostep API Error: 401 Unauthorized. Details: {\"error\":\"Invalid API key\"}"
    }
  ]
}

Distribuição

Imagens Docker

O servidor MCP está disponível como uma imagem Docker:

  • Docker Hub: [olostep/mcp-server](https://hub.docker.com/r/olostep/mcp-server)
  • Registro MCP Oficial do Docker: mcp/olostep (em breve - segurança aprimorada com assinaturas e SBOMs)
  • GitHub Container Registry: ghcr.io/olostep/olostep-mcp-server

Docker Desktop MCP Toolkit

O Olostep MCP Server está sendo adicionado ao MCP Toolkit oficial do Docker Desktop, o que significa que os usuários poderão:

  • Descobri-lo na interface do MCP Toolkit do Docker Desktop
  • Instalá-lo com um clique
  • Configurá-lo visualmente
  • Usá-lo com qualquer cliente compatível com MCP (Claude Desktop, Cursor, etc.)

Status: Envio em andamento para o Registro MCP do Docker

Plataformas Suportadas

  • linux/amd64
  • linux/arm64

Build Local

# Clone the repository
git clone https://github.com/olostep/olostep-mcp-server.git
cd olostep-mcp-server

# Build the image
npm install
npm run build
docker build -t olostep/mcp-server .

# Run locally
docker run -i --rm -e OLOSTEP_API_KEY="your-key" olostep/mcp-server

Licença

Licença ISC