alexey-pelykh/lhremote

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** — send direct messages, InMails, and connection requests; query messaging history and check for replies
- **LinkedIn engagement** — visit profiles, endorse skills, follow/unfollow, like posts, comment, and react
- **Feed & post intelligence** — read the LinkedIn feed, search posts, get post details, engagement stats, and engager lists
- **Profile enrichment** — extract emails, phones, socials, and company data from LinkedIn profiles
- **LinkedIn search** — build search URLs, resolve entity IDs, and query reference data for search filters
- **Budget & throttle monitoring** — check daily action limits and LinkedIn throttling status
- **Action discovery** — list available LinkedHelper action types with configuration schemas
Quick Start
> **Pacing**: LinkedIn monitors automated activity. See the Rate Limiting guide for recommended settings.
Prerequisites
- **Node.js** >= 24
- **LinkedHelper** desktop application (requires a paid subscription)
Installation
Or run directly with npx:
Usage with Claude Desktop
Add to your Claude Desktop configuration (claude_desktop_config.json):
Once configured, Claude can use every registered tool 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 except where its reference section says otherwise.
App Management
Account & Instance
Campaigns
Campaign Status & Retry
Campaign Actions
Campaign Targeting
Collections
Profiles & Messaging
LinkedIn Actions
Feed & Posts
LinkedIn Search & Reference
Utilities
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, CDP-connected tools accept the following, except where a tool's own reference section says otherwise. The Default column describes the MCP tools; each CLI command exposes its own subset of these flags, and the notes below give the differences that matter:
| Parameter | CLI Flag | Type | Default | Description |
|-----------|----------|------|---------|-------------|
| cdpPort | --cdp-port | number | auto-discovered | CDP debugging port |
| cdpHost | --cdp-host | string | 127.0.0.1 | CDP host address |
| allowRemote | --allow-remote | boolean | false | Allow connections to non-loopback addresses |
| accountId | *varies — see below* | number | auto-select if single account (MCP) | LinkedHelper account to act as |
**cdpPort is discovered, not defaulted.** Omit it and lhremote finds the port of the running LinkedHelper itself, whatever that port happens to be; it raises LinkedHelperNotRunningError or LinkedHelperUnreachableError when no instance is reachable. Pass a port only to target one specific instance — you do not need one to reach a LinkedHelper that is not on 9222. Two exceptions: quit-app takes cdpPort alone (no cdpHost, allowRemote or accountId) and does default to 9222; and a port is required whenever cdpHost is non-loopback, because discovery scans local processes only.
**accountId is required once more than one account is configured.** With a single account the MCP tools resolve it themselves; with several they cannot, and the call fails — most raise AccountResolutionError, while start-instance and stop-instance answer with their own message. Either way, list-accounts gives you the ID. Every tool that connects to a running LinkedHelper accepts accountId; the ones that do not are the app-management tools (find-app, launch-app, quit-app), which act on the application rather than on an account, the reference tools (build-linkedin-url, resolve-linkedin-entity, list-linkedin-reference-data, describe-actions), which open no connection, and the profile-cache readers (query-profile, query-profiles, query-profiles-bulk), which search every account's local database and cannot be scoped to one. The CLI never auto-resolves, at any account count: start-instance / stop-instance take a **required** positional , comment-on-post / react-to-post take --account-id, and no other command exposes it.