Servidor MCP Browser Use

Servidor Model Context Protocol (MCP) que conecta o browser-use ao Claude Desktop e a outros clientes compatíveis com MCP.

Visão Geral

Este repositório fornece um wrapper MCP em versão beta em torno do mecanismo de automação browser-use. Ele expõe uma única ferramenta MCP (run_browser_agent) que orquestra uma sessão de navegador, executa o agente browser-use e retorna o resultado final ao cliente. A estrutura mantém a configuração em um único lugar, torna os limites de segurança testáveis e isola as migrações upstream do browser-use da interface MCP.

Principais Capacidades

Navegação automatizada – Navegar, interagir com formulários, controlar abas, capturar capturas de tela e ler o conteúdo da página por meio de instruções em linguagem natural executadas pelo browser-use.
Gerenciamento do ciclo de vida do agente – CustomAgent envolve o agente base do browser-use para adicionar exportação de histórico, prompts mais ricos e tratamento consistente de erros entre execuções.
Configuração centralizada do navegador – create_browser_session traduz variáveis de ambiente em um BrowserSession pronto para uso, permitindo perfis persistentes, proxies e flags personalizadas do Chromium sem tocar na lógica do agente.
Integração FastMCP – server.py registra a ferramenta MCP, normaliza a configuração e garante que a sessão do navegador seja sempre encerrada corretamente.
Helpers de cliente – client.py inclui helpers assíncronos para testes ou outros processos Python que desejam exercitar o servidor MCP em processo.

Estrutura do Projeto

.
├── documentation/
│   ├── CONFIGURATION.md      # Detailed configuration reference
│   └── SECURITY.md           # Security considerations for running the server
├── sample.env.env           # Example environment variables for local development
├── src/mcp_browser_use/
│   ├── agent/                # Custom agent, prompts, message history, and views
│   ├── browser/              # Browser session factory and persistence helpers
│   ├── controller/           # Custom controller extensions for clipboard actions
│   ├── utils/                # LLM factory, agent state helpers, encoding utilities
│   ├── client.py             # Async helper for connecting to the FastMCP app
│   └── server.py             # FastMCP app and the `run_browser_agent` tool
└── tests/                    # Unit tests covering server helpers and agent features

Começando

Requisitos

Python 3.11+
Google Chrome ou Chromium (para automação local)
uv para gerenciamento de dependências (recomendado)
Opcional: Claude Desktop ou outro cliente compatível com MCP para testes de integração

Instalação

git clone https://github.com/JovaniPink/mcp-browser-use.git
cd mcp-browser-use
uv sync

Copie sample.env.env para .env (ou exporte as variáveis de outra forma) e atualize apenas os provedores que você pretende usar. Nunca envie o arquivo .env preenchido para o controle de versão.

Iniciando o servidor

uv run mcp-browser-use

O comando invoca o script de console definido em pyproject.toml, inicia o aplicativo FastMCP e registra a ferramenta run_browser_agent.

Usando com o Claude Desktop

Depois que o servidor estiver em execução, você pode registrá-lo dentro do Claude Desktop, por exemplo:

"mcpServers": {
  "mcp_server_browser_use": {
    "command": "uvx",
    "args": ["mcp-browser-use"],
    "env": {
      "MCP_MODEL_PROVIDER": "anthropic",
      "MCP_MODEL_NAME": "claude-3-5-sonnet-20241022"
    }
  }
}

Depuração

Para depuração interativa, use o MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/project run mcp-browser-use

O inspector imprime uma URL que pode ser aberta no navegador para observar chamadas de ferramentas e respostas em tempo real.

Configuração

Uma lista completa das variáveis de ambiente e seus padrões está disponível em documentation/CONFIGURATION.md. Destaques incluem:

MCP_MODEL_PROVIDER, MCP_MODEL_NAME, MCP_TEMPERATURE, MCP_MAX_STEPS, MCP_MAX_ACTIONS_PER_STEP e MCP_USE_VISION controlam o LLM e a execução do agente.
Chaves de API e endpoints específicos do provedor (ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GOOGLE_API_KEY, AZURE_OPENAI_API_KEY, etc.).
Flags de runtime do navegador (BROWSER_USE_HEADLESS, BROWSER_USE_EXTRA_CHROMIUM_ARGS, CHROME_PERSISTENT_SESSION, BROWSER_USE_PROXY_URL, ...).

Use .env + python-dotenv ou seu gerenciador de segredos preferido para manter as credenciais fora do controle de versão.

Executando Testes

uv run python -m pytest -q

Os testes cobrem o comportamento do agente personalizado, configuração do navegador, limites de entrada do MCP, redação de segredos e helpers utilitários. Uma atualização de dependência não está pronta para merge apenas porque imports ou testes unitários passam; o ambiente resolvido também deve passar em suas verificações de dependência e segurança.

Segurança

Controlar uma instância completa do navegador remotamente pode conceder amplo acesso à máquina host. Revise documentation/SECURITY.md antes de expor o servidor a ambientes não confiáveis. O mapa completo da documentação e o registro ativo de decisões de dependência estão em documentation/README.md.

A ferramenta MCP limita e restringe a entrada de tarefa/contexto antes de alocar um modelo ou sessão de navegador. Os limites de etapas em runtime são restritos, as configurações de proxy são omitidas dos logs de depuração e os valores de endpoint CDP são redigidos porque podem conter credenciais.

A migração de dependência Python 3.14/browser-use permanece retida em #45 até que o upstream permita versões transitivas corrigidas. Não force overrides incompatíveis nem suprima os achados de auditoria.

Contribuindo

Faça um fork do repositório
Crie seu branch de funcionalidade: git checkout -b my-new-feature
Faça commit das suas alterações: git commit -m 'Add some feature'
Envie para o branch: git push origin my-new-feature
Abra um pull request

Relatórios de bugs e sugestões de funcionalidades são bem-vindos—inclua logs e etapas de reprodução quando aplicável.

Browser Use

Documentação