Install
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]Para quem é
MCPSurfr (anteriormente mcp-local-rag) é um servidor MCP de busca web local para LLMs: dispensa chaves de API e os resultados são reordenados na sua própria máquina; a ordenação fica a cargo de um pequeno modelo MobileBERT que roda diretamente sobre numpy. Serve a dois perfis: quem quer acrescentar busca web a um cliente compatível com MCP sem precisar se registrar em serviços de busca nem gerenciar chaves; e fluxos de agentes que precisem de capacidades progressivamente mais profundas, da consulta pontual de trechos ao texto de páginas inteiras e daí à pesquisa profunda multimotor.
Deixe os pré-requisitos claros: precisa de um cliente que suporte servidores MCP personalizados e de uma máquina capaz de executar o comando uvx — oficialmente existe apenas este caminho de inicialização: obter o servidor a partir do GitHub via uvx. A página oficial não informa se há serviço hospedado ou interface gráfica, nem lista requisitos de sistema operacional ou clientes compatíveis; se o seu ambiente não permite baixar e executar código do GitHub, esse caminho principal não é viável.
Primeira tentativa em 3 minutos
Só existe um caminho principal recomendado, e tanto o comando quanto a configuração vêm das instruções oficiais.
Pré-requisito: poder executar uvx na máquina e um cliente que suporte configurar servidores MCP por command/args. Primeiro passo: escreva o trecho oficial na configuração de servidores MCP do cliente (o local exato varia conforme o cliente):
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]
Segundo passo: salve a configuração e recarregue a sessão; o cliente iniciará o mcpsurfr com esse comando. Na primeira execução é preciso baixar o código do GitHub pela rede; a duração e o comportamento do cache não estão documentados oficialmente.
Terceiro passo: chame a ferramenta search com uma consulta comum. É uma consulta pontual pela definição oficial, que devolve trechos relevantes e se enquadra como operação de consulta; mas a chamada dispara uma busca web real e executa o reordenamento na máquina — ser de consulta significa apenas que não escreve nada, não que não haja requisições de rede nem limites de privacidade.
Sinais de sucesso: a ferramenta devolve trechos relacionados à consulta e, na lista de ferramentas do cliente, aparecem além de search também rag_search_ddgs, rag_search_google, deep_research, deep_research_ddgs e deep_research_google. O servidor também oferece o recurso de habilidade skill://mcpsurfr-search/SKILL.md, cuja finalidade concreta não é detalhada na página oficial.
Casos de uso
Caso 1: acrescentar consulta rápida a uma conversa. Cenário: você discute no cliente um tema que pode ter novidades recentes e deixa o modelo chamar primeiro search. Ele faz uma consulta pontual e devolve trechos relevantes que o modelo pode citar diretamente; como não são necessárias chaves de API, incorporá-lo a um ambiente novo não exige registrar-se em nenhum serviço de busca. O confirmado vai até a devolução de trechos; o fatiamento e a ordenação dos trechos não são explicados oficialmente.
Caso 2: capturar o texto de páginas inteiras para organizar um tema. Cenário: quando os trechos não bastam e é preciso contexto mais completo, chame rag_search_ddgs; oficialmente ele devolve páginas inteiras como texto, o modo original do projeto. Atenção: uma chamada devolve no máximo 40.000 caracteres, ajustáveis pela variável de ambiente MCPSURFR_MAX_CHARS. Os parâmetros concretos de cada ferramenta não são detalhados item a item oficialmente; guie-se pela descrição das ferramentas que o seu cliente introspeciona. Como a série deep_research orquestra uma pesquisa em várias etapas não é explicado na página oficial — não assuma fluxos por conta própria.
Limites de uso
Natureza de leitura/escrita: as seis ferramentas são capacidades de consulta ou pesquisa; a página oficial não descreve operações que gravem arquivos locais ou submetam dados a destinos remotos. Isso é uma descrição de limites, não uma conclusão de segurança — cada chamada dispara uma busca web real e reordena resultados na máquina com MobileBERT (numpy).
Credenciais e dependências locais: o argumento oficial é dispensar chaves de API; a eventual necessidade de conta, tokens ou arquivos de dados locais não é mencionada — trate como não confirmado.
Efeitos colaterais e pontos de confirmação: a instalação baixa e executa código do GitHub via uvx; isso é inerente à configuração oficial — aceite isso antes de gravá-la. Além disso, a página oficial não descreve outros efeitos colaterais nem ações que exijam confirmação.
Limites oficiais e pontos não confirmados: as ferramentas de página inteira devolvem no máximo 40.000 caracteres por chamada, ajustáveis pela variável de ambiente MCPSURFR_MAX_CHARS. Seguem sem confirmação: a lista de clientes compatíveis, a disponibilidade e as cotas de cada backend de busca, o custo de desempenho e a possibilidade de implantação remota. Verifique essas condições no seu próprio ambiente antes de decidir com base nelas.