LinkedIn Ads MCP

Servidor LinkedIn Ads MCP

Um servidor MCP (Model Context Protocol) que permite ao Claude AI acessar e analisar seus dados de anúncios do LinkedIn. Criado para profissionais de marketing, fundadores e equipes de crescimento que desejam usar IA para otimização de campanhas, relatórios de desempenho e decisões de publicidade baseadas em dados.

[!TIP] Quer isso sem nenhuma configuração? Do mesmo autor: AdPlug é o LinkedIn Ads MCP hospedado. Faça login com OAuth (sem app de desenvolvedor do LinkedIn, sem credenciais para gerenciar), conecte Claude, ChatGPT ou Cursor em cerca de dois minutos, e obtenha Google Ads e Microsoft Ads no mesmo conector. As ferramentas de leitura são gratuitas; toda gravação é pré-visualizada antes de ser executada. Este servidor de código aberto permanece gratuito e auto-hospedado.

Instalação Rápida (Sem Necessidade de Codificação!)

Não quer lidar com questões técnicas? Basta copiar um dos prompts abaixo e colá-lo no Claude. A IA fará tudo por você!

Opção 1: Instalar com Claude Code (Recomendado)

Se você tem o Claude Code instalado, basta copiar e colar este prompt inteiro:

I want you to install the LinkedIn Ads MCP server so I can analyze my LinkedIn advertising data. Please do the following:

1. FIRST, check if Node.js is installed by running `node --version`. If not installed, tell me to install it from https://nodejs.org first.

2. Clone the repository to my home directory:
   - cd ~
   - git clone https://github.com/danielpopamd/linkedin-ads-mcp.git
   - cd linkedin-ads-mcp

3. Install dependencies and build:
   - npm install
   - npm run build

4. Create the .env file with placeholder values:
   - cp .env.example .env

5. NOW IMPORTANT - Ask me for my LinkedIn API credentials:
   - Ask: "Please provide your LinkedIn Client ID (from https://www.linkedin.com/developers/apps)"
   - Ask: "Please provide your LinkedIn Client Secret"

6. Update the .env file with the credentials I provide.

7. Set up Claude Desktop configuration:
   - Read the current Claude Desktop config file:
     - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     - Windows: %APPDATA%/Claude/claude_desktop_config.json
   - Add the linkedin-ads MCP server to mcpServers (merge with existing config if any):
     {
       "mcpServers": {
         "linkedin-ads": {
           "command": "node",
           "args": ["<FULL_PATH_TO>/linkedin-ads-mcp/dist/index.js"],
           "env": {
             "LINKEDIN_CLIENT_ID": "<MY_CLIENT_ID>",
             "LINKEDIN_CLIENT_SECRET": "<MY_CLIENT_SECRET>"
           }
         }
       }
     }
   - Replace <FULL_PATH_TO> with the actual path (e.g., /Users/username)
   - Replace the env values with my actual credentials

8. Run the authentication flow:
   - npm run auth
   - This will open my browser - tell me to authorize the app with LinkedIn

9. Tell me to restart Claude Desktop to activate the MCP server.

10. After restart, confirm setup by telling me to ask Claude: "List my LinkedIn ad accounts"

If you don't have my LinkedIn API credentials yet, first explain how to get them:
- Go to https://www.linkedin.com/developers/apps
- Create a new app (need a LinkedIn Company Page)
- Go to Products tab and request "Advertising API" access
- Go to Auth tab and add redirect URL: http://localhost:3000/callback
- Copy the Client ID and Client Secret

Start now!

Opção 2: Instalar com Claude Desktop (Baseado em Chat)

Se você está usando o Claude Desktop diretamente (sem Claude Code), copie este prompt para iniciar uma configuração guiada:

I want to install the LinkedIn Ads MCP server to analyze my LinkedIn advertising data with Claude. I'm not technical, so please guide me step by step with simple instructions.

Please walk me through:

1. **Check Prerequisites**
   - Do I have Node.js installed? (Tell me how to check and where to download if needed)
   - Do I have a LinkedIn Developer App? (If not, guide me through creating one at https://www.linkedin.com/developers/apps)

2. **Get LinkedIn API Access**
   Walk me through:
   - Creating a LinkedIn Developer App
   - Requesting Advertising API access (Products tab)
   - Adding the redirect URL: http://localhost:3000/callback (Auth tab)
   - Finding my Client ID and Client Secret

3. **Download and Install**
   Give me the exact commands to run in my terminal (one at a time):
   - How to open Terminal (Mac) or Command Prompt (Windows)
   - Clone the repository
   - Install dependencies
   - Build the project

4. **Configure Claude Desktop**
   - Tell me exactly where the config file is located
   - Give me the exact JSON to add (with placeholders for my credentials)
   - Show me how to edit the file

5. **Authenticate with LinkedIn**
   - What command to run
   - What to do when the browser opens

6. **Test the Setup**
   - Tell me to restart Claude Desktop
   - Give me a test question to ask

Please start with step 1 and wait for my response before moving to the next step. Use simple language and assume I've never used a terminal before.

O Que Você Precisa Antes de Instalar

Antes de usar qualquer método de instalação, você precisará de:

1. Node.js (versão 18 ou superior) - Baixe aqui
2. Uma Página da Empresa no LinkedIn - Necessária para criar um app de desenvolvedor
3. App de Desenvolvedor do LinkedIn com acesso à Advertising API - Crie um aqui

Obtendo Credenciais da API do LinkedIn (5-10 minutos)

1. Acesse o Portal de Desenvolvedores do LinkedIn
2. Clique em "Criar App"
3. Preencha:
   • Nome do app: "My LinkedIn Ads Analytics" (ou qualquer nome que desejar)
   • Página do LinkedIn: Selecione a página da sua empresa
   • Logotipo do app: Envie qualquer imagem quadrada
4. Após criar, vá para a aba "Produtos" → Solicite a "Advertising API" (a aprovação leva de 1 a 5 dias)
5. Vá para a aba "Auth" → Adicione a URL de redirecionamento: http://localhost:3000/callback
6. Copie seu Client ID e Client Secret - você precisará deles!

Criado Por

Daniel Popa - Consultor de Marketing de Performance e Especialista em Automação com IA

Ajudo startups ambiciosas a escalar de forma lucrativa por meio de anúncios pagos, otimização de taxa de conversão e estratégias de crescimento baseadas em dados. Com mais de 10 anos em marketing de performance e mais de US$ 100 milhões em orçamentos de anúncios gerenciados, agora foco na implementação de fluxos de trabalho de IA e automação para melhorar a eficiência e o desempenho do marketing.

Esta ferramenta foi criada para preencher a lacuna entre os dados de publicidade do LinkedIn e a análise com IA, facilitando para os profissionais de marketing obter insights acionáveis por meio de conversas em linguagem natural com o Claude.

• Site: danielpopa.me
• Foco: Marketing de Performance, Automação com IA, Estratégia de Crescimento

Instalação Manual (Para Desenvolvedores)

Se você prefere instalar manualmente ou quer mais controle, siga as instruções abaixo.

O Que Isso Faz

Este servidor MCP conecta o Claude Desktop (ou qualquer cliente compatível com MCP) à API de Marketing do LinkedIn, permitindo que você:

• Consulte o desempenho de campanhas usando linguagem natural
• Analise dados demográficos do público para entender quem está interagindo com seus anúncios
• Acompanhe conversões e leads em suas campanhas do LinkedIn
• Compare o desempenho entre períodos, campanhas ou grupos de campanhas
• Obtenha insights com IA sobre seus dados de publicidade

Exemplos de Conversas com o Claude

"Show me campaign performance for the last 30 days"
"Which job functions are responding best to my ads?"
"Compare this week's performance vs last week"
"What's my cost per lead for the lead gen campaigns?"
"Which creatives have the best CTR?"
"Show me the daily trend for conversions"

Recursos

• 25 Ferramentas Especializadas - Cobrindo contas, campanhas, criativos, públicos, conversões, análises e gerenciamento completo de campanhas (criar, atualizar, excluir)
• Métricas Abrangentes - Cada relatório inclui: Gasto, Impressões, Cliques, CTR, Alcance, Frequência, Engajamentos, Taxa de Engajamento, CPM, CPC, Conversões, Taxa de Conversão, Custo por Conversão, Penetração de Público e Tempo Médio de Permanência
• Autenticação Única com OAuth - Autentique-se uma vez e acesse todas as suas contas de anúncios do LinkedIn
• Atualização Automática de Token - Os tokens são atualizados automaticamente antes da expiração
• Tratamento de Limites de Taxa - Backoff exponencial integrado para limites de taxa da API
• Nomes Legíveis para Humanos - Os dados demográficos mostram nomes reais (não IDs) para níveis de senioridade, funções de trabalho, setores e muito mais

Pré-requisitos

1. App de Desenvolvedor do LinkedIn

Antes de usar este servidor MCP, você precisa configurar um aplicativo de desenvolvedor do LinkedIn:

1. Acesse o Portal de Desenvolvedores do LinkedIn
2. Clique em "Criar App"
3. Preencha os detalhes do seu app:
   • Nome do app: por exemplo, "My LinkedIn Ads Analytics"
   • Página do LinkedIn: Selecione a página da sua empresa
   • Logotipo do app: Envie um logotipo (obrigatório)
4. Anote seu Client ID e Client Secret

2. Solicitar Acesso à Advertising API

1. No seu app, vá para a aba "Produtos"
2. Selecione "Advertising API"
3. Envie o formulário de solicitação com sua justificativa comercial
4. Aguarde a aprovação (normalmente de 1 a 5 dias úteis)

3. Configurar OAuth

1. Vá para a aba "Auth" no seu app
2. Adicione esta URL de redirecionamento: http://localhost:3000/callback
3. Verifique se estes escopos OAuth 2.0 estão disponíveis:
   • r_ads - Ler contas de anúncios
   • r_ads_reporting - Ler dados de relatórios
   • rw_ads - Criar e gerenciar campanhas, criativos e anúncios
   • r_organization_social - Ler posts da organização (para conteúdo criativo)

Instalação

# Clone the repository
git clone https://github.com/danielpopamd/linkedin-ads-mcp.git
cd linkedin-ads-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Create your environment file
cp .env.example .env

Edite .env com suas credenciais do LinkedIn:

LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret

Autenticação

Execute o fluxo de autenticação para obter seus tokens de acesso:

npm run auth

Isso irá:

1. Abrir seu navegador na página OAuth do LinkedIn
2. Pedir que você autorize o aplicativo
3. Armazenar seus tokens localmente em ~/.linkedin-ads-mcp/tokens.json
4. Os tokens são válidos por 60 dias e são atualizados automaticamente

Configuração do Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "linkedin-ads": {
      "command": "node",
      "args": ["/full/path/to/linkedin-ads-mcp/dist/index.js"],
      "env": {
        "LINKEDIN_CLIENT_ID": "your_client_id",
        "LINKEDIN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Importante: Substitua /full/path/to/linkedin-ads-mcp pelo caminho real onde você clonou este repositório.

Após atualizar a configuração, reinicie o Claude Desktop para que as alterações tenham efeito.

Ferramentas Disponíveis

Gerenciamento de Contas

Desempenho de Campanhas e Criativos

Público e Dados Demográficos

Conversões e Geração de Leads

Análises Avançadas

Gerenciamento de Campanhas (Operações de Gravação)

Métricas Padrão

Cada relatório de desempenho inclui estas métricas:

Limites da API e Melhores Práticas

Limites da API do LinkedIn

• Limite de Taxa: 45 milhões de valores de métricas por janela de 5 minutos
• Limite de Resposta: Máximo de 15.000 elementos por resposta
• Métricas por Solicitação: Máximo de 20 métricas
• Atraso nos Dados Demográficos: 12-24 horas
• Dados de Alcance: Intervalo máximo de 92 dias

Melhores Práticas

1. Comece com a listagem de contas - Sempre liste as contas primeiro para obter IDs de conta válidos
2. Use intervalos de datas razoáveis - Intervalos mais curtos retornam mais rápido; use 30 dias para relatórios regulares
3. Seja específico com campanhas - Filtre por IDs de campanha quando souber quais campanhas analisar
4. Aproveite as comparações - Use a ferramenta de comparação para identificar rapidamente mudanças de desempenho

Estrutura do Projeto

linkedin-ads-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── auth-cli.ts           # OAuth CLI tool
│   ├── auth/
│   │   ├── oauth.ts          # OAuth 2.0 flow
│   │   └── token-store.ts    # Secure token storage
│   ├── lib/
│   │   ├── linkedin-api.ts   # LinkedIn Marketing API client
│   │   └── types.ts          # TypeScript type definitions
│   └── tools/
│       ├── accounts.ts       # Account management tools
│       ├── performance.ts    # Campaign & creative performance
│       ├── demographics.ts   # Audience demographics tools
│       ├── conversions.ts    # Conversion & lead gen tools
│       ├── analytics.ts      # Advanced analytics tools
│       └── campaign-management.ts  # Campaign CRUD & image upload tools
├── dist/                     # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── .env.example

Desenvolvimento

# Build the project
npm run build

# Run the server (for testing)
npm run dev

# Run authentication flow
npm run auth

Solução de Problemas

Erro "Não autenticado"

Execute npm run auth para autenticar com o LinkedIn.

Respostas "Limite de taxa atingido"

O servidor lida automaticamente com limites de taxa usando backoff exponencial. Se você estiver atingindo limites com frequência, reduza a frequência das suas solicitações.

Token expirado

Os tokens são atualizados automaticamente. Se você ainda estiver tendo problemas, exclua ~/.linkedin-ads-mcp/tokens.json e reautentique com npm run auth.

Acesso à API negado

Certifique-se de que seu app de desenvolvedor do LinkedIn tenha:

1. O produto "Advertising API" aprovado
2. Os escopos OAuth corretos habilitados (r_ads, r_ads_reporting)
3. Sua conta de usuário tenha acesso às contas de anúncios que você está tentando consultar

Nomes de campanhas aparecendo como "Desconhecido"

Isso normalmente significa que o ID da campanha da análise não corresponde a nenhuma campanha na sua conta. Isso pode acontecer com campanhas arquivadas ou se houver um atraso na sincronização.

Stack de Tecnologia

• Model Context Protocol (MCP) - O protocolo que permite ao Claude interagir com ferramentas externas
• LinkedIn Marketing API - API oficial para dados de publicidade do LinkedIn
• TypeScript - Desenvolvimento com segurança de tipos
• Node.js - Ambiente de execução

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

Construído com o Model Context Protocol SDK da Anthropic.

Feito com fluxos de trabalho alimentados por IA por Daniel Popa