# julia-browser-mcp

Give any AI agent the ability to browse the web, click buttons, fill forms, and interact with websites—without Chrome or Firefox installation!

## What is this?

This is an MCP (Model Context Protocol) server that lets AI assistants control a web browser. Think of it as giving your AI assistant hands to interact with websites the way you do.

## Quick Start

### Installation

Install from PyPI:

```bash
pip install julia-browser-mcp
```

### For Claude Desktop Users

1. **Add to Claude Desktop:**
   
   Open your Claude Desktop config file:
   - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   Add this configuration:
   ```json
   {
     "mcpServers": {
       "webbrowser": {
         "command": "webbrowser-mcp"
       }
     }
   }
   ```

3. **Restart Claude Desktop**

That's it! Claude can now browse websites for you.

## What Can It Do?

Once connected, you can ask Claude things like:

- "Open google.com and search for the latest news"
- "Go to example.com and tell me what's on the page"
- "Fill out this contact form with my information"
- "Click the login button and enter my username"
- "Scroll down and find the pricing section"

The AI assistant will use these tools behind the scenes:

### Website Navigation
- Open any website
- Follow links
- Get page content and titles

### Interaction
- Click buttons and links
- Type into text fields
- Submit forms

### Page Analysis
- List all clickable elements
- Search for specific text
- Get complete page information

### Scrolling
- Scroll up and down
- Jump to top or bottom
- Track scroll position

## Using with Other MCP Clients

The server works with any MCP-compatible client. Just point it to the command:

```bash
webbrowser-mcp
```

The server uses stdio transport, so it's compatible with:
- Claude Desktop
- Cline (VS Code extension)
- Any other MCP client that supports stdio

## Example Conversation

**You:** "Go to example.com and tell me what you see"

**Claude:** *Uses the `open_website` tool*

"I've opened example.com. It's a simple example website with the heading 'Example Domain' and some text explaining that this domain is for use in examples."

**You:** "Are there any links I can click?"

**Claude:** *Uses the `list_elements` tool*

"Yes, there's a 'More information...' link on the page."

## Requirements

- Python 3.8 or higher
- Node.js (required for the browser automation library)

These are automatically installed when you run `pip install -e .`

## How It Works

The server uses the Julia Browser library to control a headless browser. When an AI assistant calls a tool (like "open website"), the browser performs the action and returns the results in a format the AI can understand.

All browser state is maintained across tool calls, so the AI can perform multi-step tasks like "go to this website, fill out the form, and submit it."

## Troubleshooting

**Claude doesn't see the tools:**
- Make sure you restarted Claude Desktop after editing the config
- Check that the server is installed: run `webbrowser-mcp` in your terminal
- Verify the config file path is correct for your operating system

**Tools aren't working:**
- The browser needs internet access to visit websites
- Some websites may block automated access
- Try with simple websites first (like example.com) to verify it works

## Safety Note

This tool allows AI assistants to browse the web and interact with websites. Always review what actions the AI is planning to take, especially on websites where you're logged in or entering sensitive information.

## Author

Created by **Harish Santhanalakshmi Ganesan**

## License

MIT License - feel free to use and modify as needed!
