# LinkedIn Ads MCP Server 🚀

An open-source, token-efficient **Model Context Protocol (MCP) Server** designed specifically for **LinkedIn Campaign Manager & Ads Management**.

It allows AI assistants (such as Antigravity, Claude Desktop, Cursor, etc.) to perform deep audits, analyze campaign performance, review targeting setups, inspect ad creatives, and analyze audience demographics **without requiring a LinkedIn Developer App or official API approvals**.

---

## ✨ Key Features

* 🔒 **Zero Developer App Required:** Uses your existing authenticated browser session via anti-detect Patchright.
* ⚡ **Ultra Low Token Consumption:** Returns structured, clean JSON responses directly to the LLM instead of bulky DOM trees or screenshots.
* 📊 **Comprehensive Ads Intelligence:** Full coverage for Campaign Manager Accounts, Campaign Groups, Campaigns, Creatives, Demographics, and Conversion Tracking.
* 🐳 **Docker-Ready:** Completely containerized with persistent session storage.
* 🛡️ **Safety-First Design:** Focused on deep inspection, read-only analysis, and auditing to protect your advertising budgets.

---

## 🛠️ Available MCP Tools

| Tool Name | Scope | Description |
|---|---|---|
| `get_ad_accounts` | Accounts | Lists all accessible LinkedIn Ad Accounts, Account IDs, currency, and statuses. |
| `get_account_billing_status` | Billing | Audits billing status, payment methods, credit balance, and holds. |
| `list_campaign_groups` | Campaigns | Lists campaign groups, objectives, budgets, and schedules. |
| `list_campaigns` | Campaigns | Lists all campaigns in an account (Objective, Status, Budget, Spend, Clicks). |
| `get_campaign_details` | Targeting | Deep inspection of targeting criteria (Job titles, Industries, Geography, Bidding). |
| `list_creatives` | Creatives | Inspects ad copy, headlines, CTAs, destination URLs, and creative formats. |
| `get_campaign_analytics` | Performance | Retrieves performance KPIs (Spend, Impressions, Clicks, CTR, CPC, Conversions). |
| `get_audience_demographics` | Demographics | Analyzes audience reach across Job Function, Industry, Seniority, Company Size, etc. |
| `get_matched_audiences` | Audiences | Lists retargeting segments, contact lists, and matched audiences. |
| `get_conversion_tracking` | Conversions | Checks LinkedIn Insight Tag health and active conversion tracking rules. |
| `get_lead_gen_forms` | Leads | Audits configured Lead Gen Forms, fields collected, and submission rates. |

---

## 🚀 Quickstart & Installation

### 1. Clone the Repository
```bash
git clone https://github.com/md-riaz/linkedin-ads-mcp-server.git
cd linkedin-ads-mcp-server
```

### 2. Build the Docker Image
```bash
docker build -t linkedin-ads-mcp:latest .
```

### 3. One-Time Authentication
If you haven't authenticated your LinkedIn session in Docker yet, run the one-time login command:
```bash
docker run -it --rm \
  -v linkedin-mcp-data:/home/pwuser/.linkedin-mcp \
  -p 127.0.0.1:6080:6080 \
  stickerdaniel/linkedin-mcp-server:latest \
  --login --login-viewer
```
Open `http://127.0.0.1:6080` in your browser and sign in once. The session is permanently saved in the `linkedin-mcp-data` volume.

---

## ⚙️ MCP Client Configuration

### For Antigravity / Claude Desktop (`mcp_config.json`):
Add the following block to your `mcp_config.json`:

```json
{
  "mcpServers": {
    "linkedin-ads-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "FASTMCP_CHECK_FOR_UPDATES=off",
        "-v", "linkedin-mcp-data:/home/pwuser/.linkedin-mcp",
        "linkedin-ads-mcp:latest"
      ]
    }
  }
}
```

---

## 📁 Project Structure

```
linkedin-ads-mcp-server/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
    ├── __init__.py
    ├── server.py        # FastMCP entrypoint
    ├── config.py        # Environment & paths configuration
    ├── browser.py       # Patchright browser lifecycle manager
    └── tools/
        ├── __init__.py
        ├── accounts.py  # Ad Accounts & Billing tools
        ├── campaigns.py # Campaigns & Targeting tools
        ├── analytics.py # Performance & Demographics tools
        ├── creatives.py # Ad Creatives & Copy tools
        └── audiences.py # Matched Audiences & Insight Tag tools
```

---

## 📄 License
MIT License. Free for personal and commercial use.