Playwright Server

Playwright Server MCP

Um servidor MCP baseado em Playwright, fornecendo capacidades de automação de navegador

Componentes

Recursos

O servidor implementa um sistema simples de armazenamento de notas:

• Esquema de URI personalizado note:// para acessar notas individuais
• Cada recurso de nota possui nome, descrição e tipo MIME text/plain

Prompts

O servidor fornece um único recurso de prompt:

• summarize-notes: Cria um resumo de todas as notas armazenadas
  • Parâmetro opcional "style" controla o nível de detalhe (brief/detailed)
  • Gera um prompt que combina todas as notas atuais com a preferência de estilo

Ferramentas

O servidor implementa as seguintes ferramentas relacionadas ao Playwright:

Sessão e Navegação

• playwright_new_session: Cria uma nova sessão de navegador e abre a janela do navegador

  • Parâmetro opcional url (string), especifica a URL inicial de acesso; se não preenchido, apenas abre o navegador

• playwright_navigate: Navega para a URL especificada

  • Requer o parâmetro url (string); se não contiver o prefixo http ou https, https:// será adicionado automaticamente
  • Se não houver uma sessão de navegador ativa, uma nova sessão será criada automaticamente

Interação com a Página e Obtenção de Conteúdo

• playwright_screenshot: Tira um screenshot da página atual ou de um elemento específico

  • Requer o parâmetro name (string), nome do arquivo de screenshot, sem necessidade de incluir extensão
  • Parâmetro opcional selector (string), seletor CSS para especificar o elemento da página a ser capturado; se não preenchido, captura a página inteira

• playwright_evaluate: Executa código JavaScript no console do navegador

  • Requer o parâmetro script (string), código JavaScript a ser executado no navegador

• playwright_get_text_content: Obtém o conteúdo de texto de todos os elementos visíveis na página atual

  • Sem parâmetros
  • Filtra inteligentemente conteúdo duplicado, retornando apenas texto significativo

• playwright_get_html_content: Obtém o conteúdo HTML de um elemento específico na página

  • Requer o parâmetro selector (string), seletor CSS para localizar o elemento da página cujo HTML deve ser obtido

Operações Avançadas de Interação

• playwright_action: Suporta seleção de elementos e formas de interação ricas
  • Parâmetros obrigatórios:
    • by: Método de seleção de elementos, suporta get_by_text, get_by_placeholder, get_by_label, get_by_role, etc.
    • by_value: Valor para seleção do elemento
    • action: Tipo de operação, como fill, click, dblclick, hover, check, etc.
  • Parâmetros opcionais:
    • value: Valor da operação
    • force: Se deve forçar a execução da ação
    • delay: Atraso entre teclas (milissegundos)
    • E mais parâmetros especializados, consulte a documentação do código

Configuração

Requisitos do Sistema

• Python 3.10+
• Playwright 1.44+

Início Rápido

Instalação

Configuração do Claude Desktop

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "playwright-server": {
    "command": "uv",
    "args": [
      "--directory",
      "C:\\Users\\xxxxx\\Documents\\project\\python\\mcp\\playwright-server",
      "run",
      "playwright-server"
    ]
  }
}

"mcpServers": {
  "playwright-server": {
    "command": "uvx",
    "args": [
      "playwright-server"
    ]
  }
}

Desenvolvimento

Construção e Publicação

Preparar o pacote de publicação:

1. Sincronizar dependências e atualizar o arquivo de bloqueio:

uv sync

2. Construir a distribuição do pacote:

uv build

Isso criará distribuições de código-fonte e wheel no diretório dist/.

3. Publicar no PyPI:

uv publish

Nota: Você precisa definir as credenciais do PyPI por meio de variáveis de ambiente ou argumentos de comando:

• Token: --token ou UV_PUBLISH_TOKEN
• Ou nome de usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como o servidor MCP é executado via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente o uso do MCP Inspector.

Você pode iniciar o MCP Inspector usando o seguinte comando via npm:

npx @modelcontextprotocol/inspector uv --directory C:\Users\xxxxx\Documents\project\python\mcp\playwright-server run playwright-server

Após a inicialização, o Inspector exibirá uma URL que você pode acessar no navegador para começar a depurar.

Exemplos de Uso

Acesso Básico à Página e Screenshot

# 创建会话并导航到指定网址
await playwright_navigate(url="example.com")

# 截取整个页面
await playwright_screenshot(name="fullpage")

# 截取特定元素
await playwright_screenshot(name="logo", selector=".logo")

Operações Avançadas de Interação

# 点击文本匹配的按钮
await playwright_action(by="get_by_text", by_value="登录", action="click")

# 填充表单字段
await playwright_action(by="get_by_placeholder", by_value="用户名", action="fill", value="test@example.com")

# 检查元素是否可见
await playwright_action(by="get_by_test_id", by_value="submit-button", action="is_visible")