npm package: @leadshark/mcp-server
Description: LeadShark MCP Server - Control LinkedIn automations with natural language
Author: LeadShark
Latest version: 1.3.0

# @leadshark/mcp-server

Talk to your LinkedIn growth engine.

The LeadShark MCP server lets you control posts, automations, DMs, and limits
using natural language inside Cursor, Claude Desktop, OpenClaw, or any MCP-compatible client.

---

## What You Can Do

With MCP access, you can:

- Inspect your latest LinkedIn posts and performance
- Create comment → DM automations safely (draft-first)
- Pause, resume, and modify live automations
- Schedule posts with images and automation pre-wired
- Control daily DM volume or emergency-stop instantly

All actions are:
- auditable
- rate-limited
- reversible

Everything runs against your existing LeadShark account and respects plan limits.

---

## Who This Is For

- Existing power-users already running LeadShark automations
- Founders using Cursor or Claude as a daily control surface
- Operators who want to manage LinkedIn growth without dashboards

## Who This Is Not For

- Users new to LeadShark or new to automations
- Fully autonomous agents without human review
- High-frequency bot orchestration or spam workflows

There is a human-in-the-loop control layer by design.

---

## Requirements

- **LeadShark Pro+ or Apex subscription** (MCP access is Pro+ exclusive as of Feb 2026)
- **API Key** – generate one at https://apex.leadshark.io/docs/api
- **Node.js 18+**

---

## Installation

```bash
npm install -g @leadshark/mcp-server
```

This installs the `leadshark-mcp` command globally.

---

## Configuration

### Cursor

Add the following to your Cursor MCP config (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "leadshark": {
      "command": "leadshark-mcp",
      "env": {
        "LEADSHARK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Cursor after saving.

---

### Claude Desktop (macOS)

Add the following to:

`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "leadshark": {
      "command": "leadshark-mcp",
      "env": {
        "LEADSHARK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

## Verify Setup

Once connected, try:

```
"Show me my recent LinkedIn posts"
```

If configured correctly, LeadShark will return your latest posts with engagement
and automation status (if exists).

---

## Tool Mental Model

Think of the MCP tools as verbs on your growth system:

* **Inspect**

  * `list_recent_posts`
  * `list_automations`
  * `list_scheduled_posts`

* **Create**

  * `create_automation`
  * `schedule_post_with_automation`

* **Modify**

  * `edit_automation`
  * `edit_scheduled_post`
  * `set_daily_dm_limit`

* **Delete**

  * `cancel_scheduled_post`

You describe intent. MCP handles sequencing, safety, and execution.

---

## Available Tools

### `list_recent_posts`

Fetch your latest LinkedIn posts with engagement stats and automation status.

Examples:

```
"Show me my recent LinkedIn posts"
"What are my top performing posts?"
```

---

### `list_scheduled_posts`

List all your scheduled posts with timing, status, and automation details.
Filter by status: `pending`, `published`, `failed`, or `all` (default: `pending`).

Examples:

```
"Show me all my scheduled posts"
"What posts are scheduled for this week?"
"List my failed scheduled posts"
```

---

### `create_automation`

Create a new automation for a LinkedIn post.
All automations are created as **Draft** by default for safety.

Examples:

```
"Create an automation for my latest post — DM anyone who comments 'interested' with my ebook link"
"Set up a comment automation that replies 'DM sent!' and sends the PDF"
```

---

### `list_automations`

List all your automations with status and performance metrics.

Examples:

```
"Show me all my running automations"
"Which automations have sent the most DMs?"
```

---

### `edit_automation`

Update automation status, keywords, templates, or settings.

Examples:

```
"Pause all my automations"
"Add the keyword 'want' to my ebook automation"
"Change the DM template to include a personalized greeting"
```

---

### `edit_scheduled_post`

Update a scheduled post's content, scheduled time, or pre-automation settings.
Can edit the post copy, reschedule it, or modify automation keywords, templates, and settings.
Can only edit **pending** posts (not published/failed).

Examples:

```
"Change tomorrow's post to include the new link"
"Reschedule my 9am post to 2pm instead"
"Update Monday's post automation to use the new discount link"
"Change the keywords on my scheduled lead magnet post"
"Enable auto-like on tomorrow's scheduled post automation"
```

---

### `cancel_scheduled_post`

Cancel a scheduled post permanently. **Requires confirmation**.
Can only cancel **pending** posts.

**What you'll lose:**
- Post content (text)
- Image attachments
- Scheduling information

**What you'll keep:**
- Pre-automation template (if one was attached) — it's already saved and can be reused for future posts

Examples:

```
"Cancel tomorrow's scheduled post"
"Delete the post scheduled for Monday"
```

**Safety Note:** This action requires `confirm: true`. The post content and attachments are deleted permanently, but any pre-automation templates are preserved in your template library.

---

### `schedule_post_with_automation`

Schedule a LinkedIn post with an optional image attachment and pre-configured automation.
Supports attaching images via publicly accessible URL (JPEG, PNG, GIF, WebP up to 5MB).

Examples:

```
"Schedule this post for tomorrow at 9am with an automation that DMs the link"
"Post my new content at 2pm EST with comment replies enabled"
"Schedule a post with this infographic: https://example.com/my-image.png"
"Create a lead magnet post for Monday with the carousel image from my CDN"
```

**Image URL Requirements:**
- Must be publicly accessible (no authentication)
- Supported formats: JPEG, PNG, GIF, WebP
- Max file size: 5MB
- The image is downloaded and stored securely

---

### `set_daily_dm_limit`

Control your daily DM sending rate.
Setting the limit to `0` acts as an emergency stop.

Examples:

```
"Set my daily DM limit to 100"
"Emergency stop — pause all DM sending"
```

---

## Safety by Design

The MCP server is intentionally conservative.

* New automations always start as Draft
* Automations cannot be deleted via MCP
* Scheduled posts can be canceled (requires confirmation)
* DM volume respects your daily limits
* Emergency stops require confirmation
* Every action is logged and attributable

---

## Example Workflows

### Quick Post Automation

Goal: deliver lead magnets with ease.

```
You:
"Create a draft automation for my latest post.
Trigger on 'interested' or 'send'.
Reply with 'check your DMs 👀'
DM them my lead magnet link."
```

Result:

* Draft automation created
* No messages sent yet
* Ready for review and activation

---

### Bulk Automation Management

```
You:
"Pause all my running automations except the OpenClaw post"
```

MCP will:

* Inspect all automations
* Pause the correct set
* Leave the specified automation running

---

### Scheduled Campaign

```
You:
"Schedule my new post for 9am tomorrow with full automation.
Keywords: clawdbot, clawd, openclaw, 🦞.
DM my calendar link + github gist.
Auto-like all comments."
```

Result:

* Post is scheduled (with pre-automation details)
* Automation activates automatically when the post goes live
* Starts delivering the resource to everyone who comments the keyword

---

### Lead Magnet with Image

```
You:
"Schedule a post for Monday 9am EST with this infographic: https://cdn.example.com/guide.png
Set up automation for anyone who comments 'interested' or 'send'.
DM them my ebook link and enable auto-connect."
```

Result:

* Post scheduled with image attached
* Image downloaded and stored securely
* Automation pre-configured (activates when post goes live)
* Lead magnet infographic will publish with the post

---

## Environment Variables

| Variable            | Required | Default                     | Description                                 |
| ------------------- | -------- | --------------------------- | ------------------------------------------- |
| `LEADSHARK_API_KEY` | Yes      | —                           | Your LeadShark API key |
| `LEADSHARK_API_URL` | No       | `https://apex.leadshark.io` | API base URL                                |

---

## Rate Limits

* **100 requests/minute** burst
* **250 requests/hour** hourly limit
* **1000 requests/day** daily limit
* If getting 429 (rate-limit) errors, fallback exponentially.

---

## Error Handling

When things go wrong, you'll get a clean JSON error response:

```json
{
  "error": "Failed to fetch LinkedIn posts",
  "details": "Unable to retrieve post data from LinkedIn"
}
```

Common errors:
- **401 Unauthorized** - Invalid or expired API key
- **429 Too Many Requests** - Rate limit exceeded
- **502 Bad Gateway** - LinkedIn data temporarily unavailable
- **500 Internal Server Error** - Server-side issue

---

## Support

* MCP Docs: [https://apex.leadshark.io/docs/mcp](https://apex.leadshark.io/docs/mcp)
* API Docs: [https://apex.leadshark.io/docs/api](https://apex.leadshark.io/docs/api)
* Support: [info@leadshark.io](mailto:info@leadshark.io)

---

## License

MIT