# neko-browser

Dedicated browser MCP server for [neko-gundan](https://github.com/aliksir/neko-gundan) agents. Headed Playwright with persistent profile, fully isolated from daily-use Chrome.

## Features

- **Persistent profile**: Sessions survive restarts (cookies, localStorage, login state preserved)
- **Headed mode**: GUI visible by default for debugging and human oversight
- **23 MCP tools**: Full browser automation toolkit
- **PII masking**: Sensitive data (credit cards, SSNs, emails) auto-masked in responses
- **Process isolation**: Runs its own Chromium instance with dedicated profile directory
- **Custom favicon**: Shigoto-neko icon injected for easy identification

## Tools

| Tool | Description |
|------|-------------|
| `neko_navigate` | Navigate to URL, optionally in new tab |
| `neko_click` | Click element by index or coordinates |
| `neko_type` | Type text into element (keyboard events) |
| `neko_fill` | Set text via DOM (for contentEditable) |
| `neko_press_key` | Send keyboard key (Enter, Tab, etc.) |
| `neko_get_state` | Get page URL, title, interactive elements |
| `neko_screenshot` | Capture page screenshot |
| `neko_scroll` | Scroll page up/down |
| `neko_go_back` | Navigate back in history |
| `neko_get_html` | Get HTML of page or element |
| `neko_list_tabs` | List all open tabs |
| `neko_switch_tab` | Switch to tab by ID |
| `neko_close_tab` | Close tab by ID |
| `neko_close` | Close the browser |
| `neko_upload_file` | Upload files (direct input or dialog mode) |
| `neko_evaluate` | Execute JavaScript in page context |
| `neko_select` | Select dropdown option (by value/label/index) |
| `neko_wait_for` | Wait for selector state or navigation |
| `neko_handle_dialog` | Configure alert/confirm/prompt handling |
| `neko_hover` | Hover over element (tooltips, menus) |
| `neko_check` | Check/uncheck checkbox or radio |
| `neko_double_click` | Double-click element |
| `neko_get_attribute` | Get element attribute(s) |

## Installation

```bash
npm install
npm run build
```

## Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `NEKO_BROWSER_PROFILE` | `~/.neko-browser/profile` | Profile directory path |
| `NEKO_BROWSER_HEADLESS` | `false` | Set to `true` for headless mode |

## Usage (MCP)

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "neko-browser": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/neko-browser"
    }
  }
}
```

## License

MIT