PlayMCP is a powerful browser automation server implementing the Model Context Protocol (MCP). It provides 38 tools for web scraping, testing, and browser automation using Playwright, enabling you to control browsers programmatically with detailed interaction capabilities.
# Clone the repository
git clone https://github.com/jomon003/PlayMCP.git
cd PlayMCP
# Install dependencies
npm install
# Build the project
npm run build
# Install Playwright browsers
npx playwright install
npm run start
You should see "Browser Automation MCP Server starting..." if everything is working correctly.
Standard MCP Configuration:
{
"servers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": ["./dist/server.js"],
"cwd": "/path/to/PlayMCP",
"description": "Browser automation server using Playwright"
}
}
}
Alternative Configuration (works with VS Code GitHub Copilot):
{
"servers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/PlayMCP/dist/server.js"]
}
}
}
For Windows users:
{
"servers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\PlayMCP\\dist\\server.js"]
}
}
}
Claude Desktop:
%APPDATA%\Claude\config.json~/Library/Application Support/Claude/config.json~/.config/Claude/config.jsonVS Code MCP Extension: Add to your VS Code settings.json or MCP configuration file.
// Open browser and navigate
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })
// Extract content
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()
// Fill out a form
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "[email protected]" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })
// Enhanced scrolling with feedback
await scroll({ x: 0, y: 500, smooth: false })
// Returns: { before: {x: 0, y: 0}, after: {x: 0, y: 500}, scrolled: {x: 0, y: 500} }
// Smooth scrolling
await scroll({ x: 0, y: 300, smooth: true })
// Mouse interaction
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })
// Get page hierarchy (3 levels deep)
await getElementHierarchy({ maxDepth: 3 })
// Get detailed hierarchy with text and attributes
await getElementHierarchy({
selector: "#main-content",
maxDepth: -1,
includeText: true,
includeAttributes: true
})
// Get basic structure of a specific section
await getElementHierarchy({ selector: ".sidebar", maxDepth: 2 })
// Run custom JavaScript
await executeJavaScript({
script: "document.querySelectorAll('h1').length"
})
// Modify page content
await executeJavaScript({
script: "document.body.style.backgroundColor = 'lightblue'"
})
// Extract complex data
await executeJavaScript({
script: `
Array.from(document.querySelectorAll('article')).map(article => ({
title: article.querySelector('h2')?.textContent,
summary: article.querySelector('p')?.textContent
}))
`
})
// Take screenshots
await screenshot({ path: "./full-page.png", type: "page" })
await screenshot({ path: "./element.png", type: "element", selector: "#main-content" })
"Browser not initialized" error
openBrowser before other operationsPlaywright installation fails
# Try manual browser installation
npx playwright install chromium
Path issues in MCP configuration
Browser crashes or timeouts
headless: false for debugging# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js
You should see a JSON response listing all available tools.
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "playmcp-browser" '{"type":"stdio","command":"node","args":["./dist/server.js"],"cwd":"/path/to/PlayMCP","description":"Browser automation server using Playwright"}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": [
"./dist/server.js"
],
"cwd": "/path/to/PlayMCP",
"description": "Browser automation server using Playwright"
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": [
"./dist/server.js"
],
"cwd": "/path/to/PlayMCP",
"description": "Browser automation server using Playwright"
}
}
}3. Restart Claude Desktop for the changes to take effect