DrissionPage MCP Server

Professional browser automation for Claude Code and MCP clients powered by DrissionPage

]()

Official Repositories: GitHub | GitCode

English Version | 中文版本

🚀 What is DrissionPage MCP?

DrissionPage MCP Server is a production-ready Model Context Protocol (MCP) server that brings professional browser automation capabilities to Claude Code, Claude Desktop, and other MCP clients.

Unlike screenshot-based approaches, it provides structured, deterministic web automation through 14 powerful tools that leverage the efficiency of DrissionPage, a high-performance browser automation framework.

🌟 Why Choose DrissionPage MCP?

• LLM-Optimized: Works with structured data instead of requiring vision models
• Deterministic: Reliable element selection with CSS and XPath support
• Fast & Lightweight: Built on DrissionPage's efficient engine with minimal overhead
• Type-Safe: Full type hints and Pydantic validation for all tools
• Production Ready: Thoroughly tested and documented, ready for real-world use
• Easy Integration: Simple pip install + JSON configuration

⚡ Quick Install

# Install from PyPI
pip install drissionpage-mcp

# Verify installation
drissionpage-mcp --version

📦 Setup in Claude Code (30 seconds)

1. Edit MCP configuration:

• macOS/Linux: ~/.config/claude-code/mcp_settings.json
• Windows: %APPDATA%\claude-code\mcp_settings.json

1. Add this configuration:

   {
     "mcpServers": {
       "drissionpage": {
         "command": "drissionpage-mcp"
       }
     }
   }

1. Restart Claude Code and start using!

🎯 Quick Examples

Navigate and Screenshot

"Visit https://example.com and take a screenshot for me"

Search and Extract

"Go to Wikipedia, search for Python, and get the first paragraph"

Form Automation

"Fill out the form at https://httpbin.org/forms/post and submit it"

Data Scraping

"Get the top 10 news headlines from news.ycombinator.com"

🛠️ 14 Powerful Tools

🌐 Navigation (4 tools)

• page_navigate - Navigate to any URL
• page_go_back / page_go_forward - Browser history
• page_refresh - Reload current page

🎯 Element Interaction (3 tools)

• element_find - Find elements by CSS selector or XPath
• element_click - Click any element
• element_type - Input text into elements

📸 Page Operations (5 tools)

• page_screenshot - Capture full page or viewport
• page_resize - Adjust browser window
• page_click_xy - Click by coordinates
• page_close - Close browser
• page_get_url - Get current URL

⏱️ Wait Operations (2 tools)

• wait_for_element - Wait for element to appear (with timeout)
• wait_time - Delay execution

📚 Documentation

🏗️ Architecture

Built with clean, modular design:

DrissionMCP/
├── src/
│   ├── cli.py              # Entry point
│   ├── server.py           # MCP server
│   ├── context.py          # Browser management
│   ├── response.py         # Response formatting
│   ├── tab.py              # Page operations
│   └── tools/              # 14 automation tools
├── examples/               # Configuration templates
├── tests/                  # Unit tests
└── playground/             # Testing utilities

Key Principles:

• ✅ Type-safe Pydantic models for all tools
• ✅ Async/await throughout
• ✅ Clean separation of concerns
• ✅ Comprehensive error handling
• ✅ Full test coverage

🔧 Configuration

Basic Setup (Recommended)

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Advanced Setup

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp",
      "args": ["--log-level", "DEBUG"],
      "env": {
        "CHROME_PATH": "/custom/path/to/chrome"
      }
    }
  }
}

See examples/README.md for more configuration options.

📋 Requirements

• Python 3.8+ (3.11+ recommended)
• Chrome or Chromium browser
• Any MCP-compatible client: Claude Code, Claude Desktop, Cursor, VS Code, etc.

🧪 Testing

Verify Installation

# Quick verification
python -c "from DrissionPage import ChromiumPage; p = ChromiumPage(); print('✅ Ready')"

# Or run tests
pip install -e ".[dev]"
pytest tests/

Try It Out

# Interactive testing
python playground/local_test.py

# Quick start validation
python playground/quick_start.py

🚀 Use Cases

✅ Automated Testing - Test web applications ✅ Data Scraping - Extract structured data from websites ✅ Form Automation - Fill and submit forms ✅ Monitoring - Check for updates or changes ✅ Screenshot Verification - Capture and verify page state ✅ Content Analysis - Analyze web content programmatically

🐛 Troubleshooting

Tools Not Loading?

drissionpage-mcp --version

Should output: drissionpage-mcp 0.1.0

Browser Issues?

# Check browser installation
which google-chrome    # Linux
which chromium         # macOS

Claude Code Not Finding Server?

• Verify config file path
• Restart Claude Code after changes
• Check logs: drissionpage-mcp --log-level DEBUG

See TESTING_AND_INTEGRATION.md for complete troubleshooting guide.

📊 Project Status

Version: 0.1.0 | License: Apache 2.0 | Maintained: ✅ Active

🗺️ Roadmap

Current (v0.1.0)

• [x] 14 core automation tools
• [x] Full MCP protocol support
• [x] Production-ready codebase
• [x] Comprehensive documentation
• [x] PyPI distribution

Future (v0.2+)

• [ ] Form handling utilities
• [ ] File upload support
• [ ] Shadow DOM selectors
• [ ] Session persistence
• [ ] Proxy support
• [ ] Network interception

📖 Integration Examples

Claude Code

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

See examples/ for more client configurations.

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if needed
5. Submit a pull request

🔒 Security

• Does not store or transmit sensitive data
• Runs locally in your environment
• No external API calls
• Respects website terms of service

Best Practices:

• Don't automate without permission
• Use on test environments when possible
• Respect robots.txt
• Add appropriate delays between actions

📄 License

Licensed under Apache License 2.0 - see LICENSE

🙏 Acknowledgments

• [DrissionPage](https://github.com/g1879/DrissionPage) - Excellent browser automation library
• [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification
• [Claude](https://claude.ai) - Making AI assistants capable and useful

💬 Support

• 📖 [Full Documentation](USAGE_GUIDE.md)
• 🐛 [Report Issues](https://github.com/jumodada/DrissionMCP/issues)
• 💡 [Feature Requests](https://github.com/jumodada/DrissionMCP/discussions)
• 🔗 [GitHub Repository](https://github.com/jumodada/DrissionMCP)
• 📦 [PyPI Package](https://pypi.org/project/drissionpage-mcp/)

📈 Statistics

🌟 Show Your Support

If you find this project useful, please consider:

• ⭐ Starring on GitHub
• 📤 Sharing with your network
• 💬 Leaving feedback or suggestions
• 🐛 Reporting issues to help improve

Made with ❤️ by [Wukunyun](https://github.com/jumodada)

Ready to automate your workflows? Install now: pip install drissionpage-mcp