lhremote: LinkedHelper Automation Toolkit

CLI and MCP server for LinkedHelper automation.

This project is brought to you by Alexey Pelykh.

What It Does

lhremote lets AI assistants (Claude, etc.) control LinkedHelper through the Model Context Protocol. It can:

• App management — detect, launch, and quit LinkedHelper instances
• Account & instance control — list accounts, start/stop instances, check status
• Campaign automation — create, configure, start, stop, and monitor campaigns with full action-chain management
• People import — import LinkedIn profile URLs into campaign target lists
• Profile queries — look up and search cached LinkedIn profiles from the local database
• Messaging — query messaging history, check for new replies, scrape conversations from LinkedIn
• Action discovery — list available LinkedHelper action types with configuration schemas

New to lhremote? Check out the Getting Started guide for a step-by-step walkthrough.

Prerequisites

• Node.js >= 24
• LinkedHelper desktop application (requires a paid subscription)

Installation

npm install -g lhremote

Or run directly with npx:

npx lhremote --help

Usage with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "lhremote": {
            "command": "npx",
            "args": ["lhremote", "mcp"]
        }
    }
}

Once configured, Claude can use all 32 tools directly. A typical workflow:

1. find-app — Detect a running LinkedHelper instance (or launch-app to start one)
2. list-accounts — See available LinkedIn accounts
3. start-instance — Start an instance for an account
4. describe-actions — Explore available action types
5. campaign-create — Create a campaign from YAML/JSON configuration
6. import-people-from-urls — Import target LinkedIn profiles into the campaign
7. campaign-start — Run the campaign
8. campaign-status / campaign-statistics — Monitor progress
9. query-messages / check-replies — Review messaging results

CLI Usage

The lhremote command provides the same functionality as the MCP server. Every MCP tool has a corresponding CLI command.

App Management

lhremote find-app [--json]
lhremote launch-app [--cdp-port <port>]
lhremote quit-app [--cdp-port <port>]

Account & Instance

lhremote list-accounts [--cdp-port <port>] [--json]
lhremote start-instance <accountId> [--cdp-port <port>]
lhremote stop-instance <accountId> [--cdp-port <port>]
lhremote check-status [--cdp-port <port>] [--json]

Campaigns

lhremote campaign-list [--include-archived] [--json]
lhremote campaign-create --file <path> | --yaml <config> | --json-input <config> [--cdp-port <port>] [--json]
lhremote campaign-get <campaignId> [--cdp-port <port>] [--json]
lhremote campaign-export <campaignId> [--format yaml|json] [--output <path>] [--cdp-port <port>]
lhremote campaign-update <campaignId> [--name <name>] [--description <text>] [--clear-description] [--cdp-port <port>] [--json]
lhremote campaign-delete <campaignId> [--cdp-port <port>] [--json]
lhremote campaign-start <campaignId> [--person-ids <ids>] [--person-ids-file <path>] [--cdp-port <port>] [--json]
lhremote campaign-stop <campaignId> [--cdp-port <port>] [--json]
lhremote campaign-status <campaignId> [--include-results] [--limit <n>] [--cdp-port <port>] [--json]
lhremote campaign-statistics <campaignId> [--action-id <id>] [--max-errors <n>] [--cdp-port <port>] [--json]
lhremote campaign-retry <campaignId> [--person-ids <ids>] [--person-ids-file <path>] [--cdp-port <port>] [--json]

Campaign Actions

lhremote campaign-add-action <campaignId> --name <name> --action-type <type> [--description <text>] [--cool-down <ms>] [--max-results <n>] [--action-settings <json>] [--cdp-port <port>] [--json]
lhremote campaign-remove-action <campaignId> <actionId> [--cdp-port <port>] [--json]
lhremote campaign-reorder-actions <campaignId> --action-ids <ids> [--cdp-port <port>] [--json]
lhremote campaign-move-next <campaignId> <actionId> [--person-ids <ids>] [--person-ids-file <path>] [--cdp-port <port>] [--json]

Campaign Targeting

lhremote campaign-exclude-list <campaignId> [--action-id <id>] [--cdp-port <port>] [--json]
lhremote campaign-exclude-add <campaignId> --person-ids <ids> | --person-ids-file <path> [--action-id <id>] [--cdp-port <port>] [--json]
lhremote campaign-exclude-remove <campaignId> --person-ids <ids> | --person-ids-file <path> [--action-id <id>] [--cdp-port <port>] [--json]
lhremote import-people-from-urls <campaignId> --urls <urls> | --urls-file <path> [--cdp-port <port>] [--json]

Profiles & Messaging

lhremote query-profile --person-id <id> | --public-id <slug> [--json]
lhremote query-profiles [--query <text>] [--company <name>] [--limit <n>] [--offset <n>] [--json]
lhremote query-messages [--person-id <id>] [--chat-id <id>] [--search <text>] [--limit <n>] [--offset <n>] [--json]
lhremote check-replies [--since <timestamp>] [--cdp-port <port>] [--json]
lhremote scrape-messaging-history [--cdp-port <port>] [--json]

Utilities

lhremote describe-actions [--category <category>] [--type <type>] [--json]

MCP Tools

Common Parameters

Most tools and CLI commands connect to LinkedHelper via the Chrome DevTools Protocol (CDP). In addition to the tool-specific parameters listed below, all CDP-connected tools accept:

Security warning: Enabling allowRemote permits CDP connections to remote hosts. CDP is an unsandboxed protocol that grants full control over the target browser — equivalent to remote code execution. Only enable this when the network path between your machine and the target host is fully secured (e.g., SSH tunnel, VPN, or trusted LAN).

App Management

find-app

Detect running LinkedHelper application instances and their CDP connection details.

No parameters.

launch-app

Launch the LinkedHelper application with remote debugging enabled.

quit-app

Quit the LinkedHelper application.

Account & Instance

list-accounts

List available LinkedHelper accounts. Returns account ID, LinkedIn ID, name, and email for each account.

start-instance

Start a LinkedHelper instance for a LinkedIn account.

stop-instance

Stop a running LinkedHelper instance.

check-status

Check LinkedHelper connection status, running instances, and database health.

Campaigns

campaign-list

List existing campaigns with summary statistics.

campaign-create

Create a new campaign from YAML or JSON configuration. Provide exactly one of yamlConfig or jsonConfig.

campaign-get

Get detailed campaign information including action chain.

campaign-export

Export campaign configuration as YAML or JSON.

campaign-update

Update a campaign's name and/or description.

campaign-delete

Delete (archive) a campaign.

campaign-start

Start a campaign with specified target persons.

campaign-stop

Stop a running campaign.

campaign-status

Check campaign execution status and results.

campaign-statistics

Get per-action statistics for a campaign.

campaign-retry

Reset specified people for re-run in a campaign.

Campaign Actions

campaign-add-action

Add a new action to a campaign's action chain. Use describe-actions to explore available action types.

campaign-remove-action

Remove an action from a campaign's action chain.

campaign-reorder-actions

Reorder actions in a campaign's action chain.

campaign-move-next

Move people from one action to the next in a campaign.

Campaign Targeting

campaign-exclude-list

View the exclude list for a campaign or action.

campaign-exclude-add

Add people to a campaign or action exclude list.

campaign-exclude-remove

Remove people from a campaign or action exclude list.

import-people-from-urls

Import LinkedIn profile URLs into a campaign action target list. Idempotent — previously imported URLs are skipped.

Profiles & Messaging

query-profile

Look up a cached LinkedIn profile from the local database by person ID or public ID.

query-profiles

Search for profiles in the local database with name, headline, or company filters.

query-messages

Query messaging history from the local database.

check-replies

Check for new message replies from LinkedIn.

scrape-messaging-history

Scrape all messaging history from LinkedIn into the local database. This is a long-running operation that navigates LinkedIn's messaging interface.

Utilities

describe-actions

List available LinkedHelper action types with descriptions and configuration schemas.

Known Limitations

• Platform support: LinkedHelper runs on macOS, Windows, and Linux. Binary paths are detected automatically but can be overridden with the LINKEDHELPER_PATH environment variable.
• Instance startup time: Starting an instance loads LinkedIn, which may take up to 45 seconds.
• Profile data is cached: query-profile and query-profiles search the local LinkedHelper database. Profiles must have been visited or imported by LinkedHelper to appear in results.
• Messaging scrape is slow: scrape-messaging-history navigates LinkedIn's messaging UI and can take several minutes depending on conversation volume.
• Same-machine requirement: lhremote must run on the same machine as LinkedHelper. CDP connections are localhost-only by default (for security), and database access requires direct file system access to the LinkedHelper SQLite database.

Troubleshooting

LinkedHelper is not running

Error: LinkedHelper is not running (no CDP endpoint at port 9222)

Solution: Use launch-app to start LinkedHelper, or start it manually. lhremote communicates with LinkedHelper via the Chrome DevTools Protocol (CDP), which requires the application to be running.

Application binary not found

Error: LinkedHelper application binary not found. Set LINKEDHELPER_PATH to override.

Solution: Install LinkedHelper from linkedhelper.com. If installed in a non-standard location, set the LINKEDHELPER_PATH environment variable to the binary path.

No accounts found

Error: No accounts found.

Solution: Open LinkedHelper and configure at least one LinkedIn account before using lhremote.

Multiple accounts found

Error: Multiple accounts found. Specify accountId. Use list-accounts to see available accounts.

Solution: Use list-accounts to see available accounts, then pass the desired accountId to start-instance, stop-instance, or other tools.

No instance running

Error: No LinkedHelper instance is running. Use start-instance first.

Solution: Run start-instance before using campaign or messaging tools. An instance must be running to interact with LinkedIn.

Instance initialization timeout

Error: Instance started but failed to initialize within timeout.

Solution: The instance was started but took too long to finish loading. This can happen on slow connections. Try again; the instance may still be starting in the background. Use check-status to verify.

Database not found

Error: No database found for account

Solution: The LinkedHelper database file is missing for the specified account. Ensure the account has been used at least once in LinkedHelper so that a local database has been created.

Disclaimer

lhremote is an independent project not affiliated with, endorsed by, or officially connected to:

• LinkedIn or LinkedIn Corporation
• LinkedHelper or its parent company

LinkedIn is a trademark of LinkedIn Corporation. LinkedHelper is a trademark of its respective owner.

Purpose

This project enables interoperability between automation tools and LinkedHelper, as permitted under DMCA § 1201(f). Implementation is based on publicly observable behavior (Chrome DevTools Protocol) without access to protected source code.

What This Project Does NOT Do

• Circumvent copy protection or licensing
• Bypass LinkedHelper authentication
• Enable use without a valid LinkedHelper subscription
• Provide access to LinkedIn without LinkedHelper

User Responsibility

Use of lhremote requires a valid LinkedHelper subscription and is subject to LinkedHelper's and LinkedIn's terms of service. Users accept all responsibility for compliance.

Ethical Use

This tool is for legitimate productivity. Do NOT use for spam, scraping at scale, or harassment.

License

AGPL-3.0-only — For commercial licensing, contact the maintainer.