Termux Puppeteer MCP Server

A Puppeteer MCP (Model Context Protocol) server that works on Android Termux by running Chromium inside an Alpine Linux container via proot-distro.

Why This Exists

Standard Puppeteer MCP servers don't work on Android/Termux because:

• No ARM build of Chrome exists
• Puppeteer requires a Chromium-based browser

This solution uses Alpine Linux in a containerized environment to run Chromium, while the MCP server runs in Termux and bridges commands to Alpine.

Quick Setup

Automated installation (recommended):

bash setup.sh

The script will automatically:

1. Install proot-distro
2. Install Alpine Linux
3. Install Chromium and Node.js in Alpine
4. Install Puppeteer in Alpine
5. Set up the MCP server in Termux
6. Create configuration files

No device root required!

Takes about 5-10 minutes depending on your connection.

Manual Setup

If already set up or prefer manual installation:

• ✅ Alpine Linux installed via proot-distro
• ✅ Chromium installed in Alpine
• ✅ Node.js and npm in both Termux and Alpine
• ✅ Puppeteer installed in Alpine

Available Tools

The server provides these Puppeteer tools via MCP:

1. puppeteer_navigate - Navigate to a URL and get page content/title
2. puppeteer_screenshot - Take screenshots (returns base64)
3. puppeteer_pdf - Generate PDFs from URLs (returns base64)
4. puppeteer_evaluate - Execute JavaScript in page context
5. puppeteer_click - Click elements on pages

Usage with Claude Code

Add this to your Claude Code MCP settings:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["/data/data/com.termux/files/home/termux-puppeteer-mcp/index.js"]
    }
  }
}

Or use the absolute path to node:

{
  "mcpServers": {
    "puppeteer": {
      "command": "/data/data/com.termux/files/usr/bin/node",
      "args": ["/data/data/com.termux/files/home/termux-puppeteer-mcp/index.js"]
    }
  }
}

Testing

You can test the server using the MCP inspector or by running:

node index.js

The server communicates via stdio using the MCP protocol.

How It Works

1. MCP server runs in Termux (native Android environment)
2. When a tool is called, it generates Puppeteer JavaScript code
3. Code is executed inside Alpine Linux using proot-distro login alpine
4. Chromium runs in Alpine with appropriate flags (--no-sandbox, etc.)
5. Results are returned back through the MCP protocol

Example Commands

From Claude Code:

• "Take a screenshot of example.com"
• "Get the title of google.com"
• "Generate a PDF of github.com"
• "Click the login button on example.com"

Notes

• No device root required (proot works without root)
• Chromium runs in headless mode
• Screenshots are compressed JPEG (quality 60%, 800x600) to fit MCP token limits
• PDFs are returned as base64
• The proot warning about sanitizing bindings is normal and can be ignored

Files

• setup.sh - Automated installation script
• index.js - MCP server implementation
• package.json - Node.js dependencies
• .mcp.json - MCP server configuration for Claude Code
• README.md - This file
• SETUP.md - Detailed setup guide

Sharing

To share this setup online:

1. The setup.sh script contains all installation steps
2. Users can run it on any Termux installation
3. Works on ARM64 Android devices without root

License

MIT - Feel free to use and modify