Backpack MCP

Backpack MCP is a self-contained browser bridge that turns websites you are already signed in to into Model Context Protocol tools. It runs from a cloned repository, uses a local Python environment and a local Chromium install, and includes a local dashboard for signing in and administering extensions.

There is no package build, installer or .exe. backpack.cmd sets up the local environment on first run and then runs the Python server.

Backpack automates accounts and sites you are authorised to use. Automating a website may violate its terms of service. You are responsible for how you use it.

Requirements

• Python 3.11 or newer on PATH

• Windows for backpack.cmd (macOS/Linux can use the module entry point)

• Network access on first run for Python dependencies and the local Chromium download

Related MCP server: cdp-bridge

Why Backpack

• Self-contained. The Python environment, Chromium, profiles, cookies, screenshots, downloads, logs and settings all live inside the cloned folder. Deleting .backpack/ resets site data.

• Browser-first. No vendor API keys are required. Backpack uses real, persistent browser profiles, so it uses the same sessions you sign in to.

• Headless by default. Full Chromium new-headless mode is used for tool calls. A visible window is only opened for sign-in or verification, and live screenshots are available on demand.

• Extension driven. Every site is a small Python class with typed tools. Adding a website does not require changing Backpack's core.

• One browser owner. A local daemon owns the browser, so the dashboard and MCP clients share sessions without Chromium profile-lock races.

Clone and run

git clone <repository-url> backpack-mcp
cd backpack-mcp
.\backpack.cmd browser install
.\backpack.cmd ui

On first run, backpack.cmd creates .venv/, installs requirements.txt, and then runs the CLI. Chromium is downloaded into .backpack/browsers. No global packages are installed.

If PowerShell blocks local scripts, use cmd /c backpack.cmd ... or run the command from a regular Command Prompt.

On macOS or Linux, create a local venv and use the module entry point:

python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m backpack_mcp browser install
.venv/bin/python -m backpack_mcp ui

Dashboard and login

.\backpack.cmd ui starts the local daemon and opens the dashboard. Use Open setup for each site, sign in, and close the window. Headless tool calls reuse that profile.

For sites that show a Cloudflare verification page, keep the setup window open for the tool call. Backpack reports verification challenges instead of silently failing. If a site keeps challenging headless sessions, add this to its settings in the dashboard:

{ "force_headed": true }

The dashboard screenshot view is manual by default. Do not enable Live while you are interacting with a CAPTCHA or verification widget; repeated captures can interfere with it.

The dashboard is protected by a loopback-only token. If you lose the URL, run .\backpack.cmd ui again or .\backpack.cmd daemon status --url.

Built-in site extensions

Built-ins live in backpack_mcp/extensions/builtin/. Project extensions live in extensions/ and load after the built-ins.

MCP client configuration

Point the client at backpack.cmd through cmd.exe so batch-file setup works reliably:

{
  "mcpServers": {
    "backpack": {
      "command": "C:\\Windows\\System32\\cmd.exe",
      "args": [
        "/c",
        "C:\\path\\to\\backpack-mcp\\backpack.cmd",
        "serve"
      ],
      "cwd": "C:\\path\\to\\backpack-mcp"
    }
  }
}

backpack.cmd serve runs the MCP stdio server and starts the daemon automatically if it is not already running. It exposes:

• Generic tools: backpack_list_extensions, backpack_status, backpack_list_tools, backpack_screenshot, backpack_open_login, backpack_close_browser, backpack_reload_extensions, backpack_logout

• Extension tools namespaced as <extension>__<tool>

Ask your client to call backpack_list_extensions first.

Writing an extension

from typing import Annotated

from playwright.async_api import Page
from pydantic import Field

from backpack_mcp.extensions import BackpackExtension, ToolResult, tool


class ExampleExtension(BackpackExtension):
    id = "example"
    name = "Example"
    description = "A minimal extension."
    site = "https://example.com"
    requires_login = False

    @tool(description="Return the page title.", read_only=True)
    async def title(self, page: Page) -> ToolResult:
        return ToolResult.ok(await page.title())

    @tool(description="Search the site.")
    async def search(
        self,
        page: Page,
        query: Annotated[str, Field(description="Search query")],
    ) -> ToolResult:
        await self.ctx.goto(page)
        ...

Create a starter with:

.\backpack.cmd extensions new mysite --name "My Site" --site https://example.com

The extensions/_template directory and the examples/demo extension are reference material. See Writing extensions for the full API.

Self-contained data

Everything Backpack persists is under .backpack/ (or BACKPACK_HOME when set):

.backpack/
  browsers/          # project-local Playwright Chromium
  profiles/<id>/     # persistent browser profile per extension
  screenshots/       # retained screenshots
  downloads/<id>/    # files downloaded by a session
  settings/          # per-extension JSON settings
  logs/              # rotating application and daemon logs
  runtime/           # daemon metadata and local API token
  tmp/               # temporary browser files

The Python environment lives in .venv/. To reset Backpack, stop the daemon and delete .backpack/; then run .\backpack.cmd browser install again. Use .\backpack.cmd logout <id> to clear one site only.

Security

• The daemon binds to loopback only and requires a random per-process token.

• Browser profiles are credentials. Keep .backpack/ private and never commit it.

• Extension code runs as local Python with your privileges. Only install extensions you trust.

• Backpack does not send telemetry and does not use external CDN assets in its dashboard.

• Backpack does not solve CAPTCHAs or bypass access controls. Use it within each site's terms.

CLI reference

All commands go through the root launcher:

Library use

Backpack can also be imported from another Python program. Run that program from the repository root, or put the repository root on PYTHONPATH:

import asyncio

from backpack_mcp import Backpack


async def main() -> None:
    async with Backpack() as backpack:
        tools = await backpack.list_tools()
        print([tool["name"] for tool in tools])

        result = await backpack.invoke(
            "google__search",
            {"query": "what causes thunder", "num_results": 5},
        )
        print(result.text)


asyncio.run(main())

Library mode owns the browser in-process. Do not use it against the same profiles while the daemon is running.

Documentation

• Architecture

• Writing extensions

• Configuration reference

Development

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m ruff check backpack_mcp tests extensions examples
.\.venv\Scripts\python.exe -m ruff format --check backpack_mcp tests extensions examples
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m pytest

Unit and API tests do not require a browser. Browser integrations are tested manually because they depend on signed-in site profiles and live third-party UIs.

License

MIT. See LICENSE.