Python CDP Browser Scripts

Create Python functions that connect to running MCP browser agents via Chrome DevTools Protocol (CDP) and perform complete browser automation workflows. Replaces Claude browser MCP calls entirely — zero LLM tokens consumed.

Usage

/python-cdp-scripts <platform> <action-description>
/python-cdp-scripts linkedin "scrape engagement stats for our comments"
/python-cdp-scripts linkedin "check if posts are deleted"
/python-cdp-scripts linkedin "read unread DM conversations"

How It Works

Unlike browser-script (JS scripts run via Claude's browser_run_code tool calls), this approach:

• Python connects directly to the running MCP browser via CDP port
• Reuses the existing logged-in session (cookies, tabs)
• Returns structured JSON to stdout
• Called from shell scripts — Claude is never involved
• Zero LLM tokens consumed for the automation

Architecture

Each platform has a single Python file (e.g., scripts/linkedin_browser.py) with:

1. find_cdp_port() — scans running Chrome/Chromium processes for remote-debugging-port flags
2. get_browser_and_page() — connects via CDP, reuses existing platform tab (critical: new pages don't inherit cookies)
3. Individual command functions (e.g., search_posts(), discover_notifications(), scrape_stats())
4. CLI interface via if __name__ == "__main__" with subcommands

Workflow

Step 1: Identify the automation target

Look at the shell script (skill/*.sh) for steps that currently use claude -p with browser MCP calls purely for automation (no content decisions). These are candidates for Python CDP replacement.

Step 2: Write the function

Add to the existing platform script (e.g., scripts/linkedin_browser.py):

def new_function(param1, param2):
    """One-line description of what this does.

    Returns JSON: {"field": "value", ...}
    """
    from playwright.sync_api import sync_playwright

    with sync_playwright() as p:
        browser, page, is_cdp = get_browser_and_page(p)

        try:
            page.goto(url, wait_until="domcontentloaded")
            page.wait_for_timeout(3000)

            # Use page.evaluate() for in-page JS
            result = page.evaluate("""() => {
                // DOM manipulation, internal API calls, etc.
                return { data: "value" };
            }""")

            return result

        finally:
            if not is_cdp:
                page.close()
                browser.close()

Step 3: Add CLI subcommand

# In main()
elif cmd == "new-command":
    result = new_function(sys.argv[2], sys.argv[3])
    print(json.dumps(result, indent=2))

Step 4: Test standalone

python3 scripts/linkedin_browser.py new-command arg1 arg2

Step 5: Update the shell script

Replace the claude -p block with direct Python call:

# Old: claude -p "Navigate to... run JS... extract..." (30-50K tokens)
# New:
RESULT=$(python3 "$REPO_DIR/scripts/linkedin_browser.py" new-command arg1 arg2)
# Process $RESULT with python3 -c or jq (0 tokens)

Design Rules

1. Reuse existing tabs — CDP-connected browsers share cookies only with existing tabs. Creating context.new_page() opens a blank session. Always find and reuse the platform's existing tab.

2. Prefer page.evaluate() for data extraction — runs JS in-page, has access to cookies for internal API calls (Voyager API, etc.). Faster than DOM navigation.

3. Use internal APIs when available — LinkedIn's Voyager API (/voyager/api/...) provides structured data. Extract CSRF token from cookies, fetch with proper headers. More reliable than DOM scraping.

4. Return structured JSON — every function returns a dict/list that gets json.dumps()-ed to stdout. Shell scripts consume with python3 -c "import json...".

5. Handle CDP port discovery robustly — multiple Chrome instances may be running. Scan all ports, check /json endpoint for pages, prefer ports with logged-in platform pages (URLs without /login/ or /uas/).

6. Generous timeouts — social sites are slow. 3s after navigation, 2s after scroll, 1s after click. Use wait_until="domcontentloaded" not "networkidle" (can hang).

7. Stderr for diagnostics, stdout for data — print debug info to stderr, JSON output to stdout. Shell scripts capture with cmd 2>/dev/null.

8. One function = one complete workflow — "extract all notifications", "scrape stats for a URL", "check if post is deleted". Not individual clicks.

9. Fallback gracefully — if CDP connection fails or page structure changed, return {ok: false, error: "reason"} instead of crashing.

10. No LLM decisions in Python — the script does mechanical work only. Content decisions stay in Claude prompts.

When NOT to Use

• Content generation — Claude needs to decide what to write
• Complex multi-step decisions — "if post is about X, do Y, otherwise Z" where X requires understanding
• One-off debugging — just use browser_snapshot manually
• Actions that need Claude's judgment mid-flow — use browser-script instead

The split: Python CDP handles MECHANICAL work (navigate, extract, scrape, post via API). Claude handles JUDGMENT work (pick posts, write comments, decide strategy).

CDP Connection Details

Finding the browser port

def find_cdp_port():
    # Scan ps aux for --remote-debugging-port=NNNN
    # Check each port's /json endpoint for platform pages
    # Prefer ports with logged-in pages (feed/notifications, not login/uas)

Reusing existing tabs (CRITICAL)

def get_browser_and_page(playwright):
    browser = playwright.chromium.connect_over_cdp(f"http://localhost:{port}")
    context = browser.contexts[0]  # Reuse existing context
    # Find existing platform tab - DO NOT create new pages
    for pg in context.pages:
        if "linkedin.com" in pg.url and "/login" not in pg.url:
            return browser, pg, True  # is_cdp=True

New pages created via context.new_page() do NOT inherit cookies from the MCP browser session. This is the #1 gotcha.

Platform Notes

LinkedIn

• CDP port: found by scanning Chrome processes for --remote-debugging-port
• Prefer ports with logged-in pages (feed, notifications URLs, not login/uas)
• Voyager API: /voyager/api/voyagerIdentityDashNotificationCards for notifications
• Activity IDs: hidden in new React DOM, extract via control menu's Report link (updateUrn param)
• Comment identification: use button[aria-label*="View more options for <name>"] to find our comment container
• Old DOM selectors (article.comments-comment-entity) no longer work -- LinkedIn uses obfuscated CSS classes
• API for posting: linkedin_api.py handles comments, replies, likes via REST API
• Agent config: ~/.claude/browser-agent-configs/linkedin-agent.json

Reddit (future)

• old.reddit.com is simpler to automate
• Reddit API exists for most operations -- prefer API over browser
• Agent: reddit-agent

Twitter/X (future)

• Twitter API handles most operations
• Browser needed for: reading DMs, visual verification
• Agent: twitter-agent

Existing Functions

linkedin_browser.py

Command	Action	Input	Output
notifications	Extract notifications via Voyager API	none	[{type, commentUrn, activityId, authorName, ...}]
search URL	Search posts, extract activity IDs	search URL	{activity_ids: [...], posts: [{activity_id, author, text}]}
comment-context URL	Get comment thread for a post	post URL	{activity_id, comments: [{author, content}]}
activity-id URL	Extract activity ID from post	post URL	{activity_id, post_text, author}
stats URL [PREFIX]	Scrape reaction count on our comment	post URL + optional content prefix	{found, reactions, comment_preview}
stats-batch JSON	Batch stats for multiple posts	JSON array of [{id, url, content_prefix}]	[{id, url, found, reactions, comment_preview}]
audit URL	Check if post is live or deleted	post URL	{status, reactions, comments, views}
audit-batch JSON	Batch audit for multiple posts	JSON array of [{id, url}]	[{id, url, status, reactions, comments, views}]

linkedin_api.py (companion REST API wrapper)

Command	Action	Input	Output
comment ACTIVITY_ID TEXT	Post comment	activity ID + text	{ok, comment_urn, our_url}
reply ACTIVITY_ID PARENT_URN TEXT	Reply to comment	activity ID + parent URN + text	{ok, reply_urn, permalink}
post TEXT	Create new post	text	{ok, post_urn}
like ACTIVITY_ID	Like a post	activity ID	{ok}
delete POST_URN	Delete a post	post URN	{ok}
whoami	Get authenticated user info	none	{ok, name, email}

vs browser-script Approach

	Python CDP	browser-script (JS)
Token cost	0	2 tool calls (~2-5K tokens)
When to use	Shell script automation, no Claude in loop	Mid-Claude-session, Claude deciding content
Execution	python3 script.py cmd args	browser_run_code via MCP
Session	Connects to existing browser via CDP	Runs inside MCP browser agent
Best for	Stats, audit, notifications, search	Edit comment, post with dynamic text