LinkedIn MCP Server Documentation

Table of Contents

1. Introduction
2. Architecture Overview
3. Installation Guide
4. Configuration
5. API Reference
6. LinkedIn Functionality
7. n8n Integration
8. Deployment Guide
9. Testing
10. Troubleshooting
11. Security Considerations
12. Limitations and Compliance

Introduction

The LinkedIn MCP Server is a Model Context Protocol (MCP) implementation that enables integration between n8n and LinkedIn without requiring official API access. It uses web automation techniques with Puppeteer to interact with LinkedIn's web interface, providing functionality for profile management, connections, messaging, posts, and job searching.

Purpose

This server allows you to automate LinkedIn interactions through n8n workflows, enabling various use cases:

• Automated connection management
• Profile data extraction and analysis
• Messaging automation
• Content posting and engagement
• Job search and application processes

Key Features

• Profile Management: View and search LinkedIn profiles
• Connection Management: Send connection requests and manage connections
• Messaging: Send messages and read conversations
• Post Interaction: Create, like, comment on, and share posts
• Job Search: Search for jobs, view details, and apply when possible
• MCP Protocol Support: Seamless integration with n8n through the Model Context Protocol

Architecture Overview

The LinkedIn MCP Server follows a modular architecture designed for maintainability and extensibility:

Core Components

1. MCP Server Core: Implements the JSON-RPC 2.0 based protocol with SSE support
2. LinkedIn Automation Engine: Uses Puppeteer for web automation
3. LinkedIn Functionality Modules: Provides specific LinkedIn features
4. n8n Integration Layer: Connects the MCP server to n8n workflows

Technical Stack

• Node.js: Runtime environment
• Express.js: Web server framework
• Puppeteer: Headless browser automation
• Puppeteer-Extra: Enhanced Puppeteer with stealth capabilities
• Winston: Logging system
• JSON-RPC 2.0: Communication protocol for MCP

Directory Structure

mcp-linkedin-project/
├── src/
│   ├── index.js                  # Main entry point
│   ├── routes/                   # API routes
│   │   └── mcp.js                # MCP protocol routes
│   ├── controllers/              # Business logic
│   │   └── linkedin-controller.js # LinkedIn functionality controller
│   ├── services/                 # Core services
│   │   ├── browser.js            # Puppeteer browser management
│   │   ├── linkedin-auth.js      # LinkedIn authentication
│   │   ├── linkedin-profile.js   # Profile functionality
│   │   ├── linkedin-connection.js # Connection functionality
│   │   ├── linkedin-messaging.js # Messaging functionality
│   │   ├── linkedin-post.js      # Post functionality
│   │   └── linkedin-job.js       # Job functionality
│   ├── models/                   # Data models
│   ├── utils/                    # Utility functions
│   └── config/                   # Configuration files
├── test/                         # Test scripts
│   ├── test-mcp.js               # MCP server tests
│   ├── n8n-webhook-test.js       # n8n webhook simulator
│   └── n8n-workflow-example.js   # Example n8n workflow
├── docs/                         # Documentation
├── .env.example                  # Environment variables template
├── package.json                  # Dependencies and scripts
├── start.sh                      # Server start script
└── test.sh                       # Test runner script

Installation Guide

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• A LinkedIn account
• Internet access

Local Installation

1. Clone the repository or download the source code:

git clone https://github.com/yourusername/mcp-linkedin-project.git
cd mcp-linkedin-project

2. Install dependencies:

npm install

3. Create environment configuration:

cp .env.example .env

4. Edit the .env file with your LinkedIn credentials and other settings:

PORT=3000
MCP_SERVER_NAME="LinkedIn MCP Server"
MCP_SERVER_VERSION="0.1.0"

# LinkedIn Credentials
LINKEDIN_USERNAME="your-linkedin-email"
LINKEDIN_PASSWORD="your-linkedin-password"

# Security Settings
JWT_SECRET="your-secure-random-string"
COOKIE_SECRET="another-secure-random-string"

5. Start the server:

./start.sh

Docker Installation

A Dockerfile is provided for containerized deployment:

1. Build the Docker image:

docker build -t linkedin-mcp-server .

2. Run the container:

docker run -p 3000:3000 --env-file .env linkedin-mcp-server

Proxmox LXC Container Installation

For deployment on Proxmox as an LXC container, refer to the Proxmox Deployment Guide.

Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	3000
MCP_SERVER_NAME	Server name	"LinkedIn MCP Server"
MCP_SERVER_VERSION	Server version	"0.1.0"
LINKEDIN_USERNAME	LinkedIn account email/username	-
LINKEDIN_PASSWORD	LinkedIn account password	-
JWT_SECRET	Secret for JWT token generation	-
COOKIE_SECRET	Secret for cookie encryption	-
MAX_REQUESTS_PER_HOUR	Rate limit for requests	50
RATE_LIMIT_WINDOW_MS	Rate limit window in milliseconds	3600000
HEADLESS	Run browser in headless mode	true
USER_AGENT	Browser user agent	Mozilla/5.0...
LOG_LEVEL	Logging level	info
PROXY_SERVER	Proxy server (optional)	-
PROXY_USERNAME	Proxy username (optional)	-
PROXY_PASSWORD	Proxy password (optional)	-
PROXY_TYPE	Proxy type (http, https, socks5)	http

Browser Configuration

The browser service can be configured for different environments:

• Headless Mode: Set HEADLESS=true for server environments or HEADLESS=false for debugging
• User Agent: Customize with USER_AGENT to avoid detection
• Proxy Support: Configure proxy settings for IP rotation and avoiding rate limits

API Reference

The LinkedIn MCP Server implements the Model Context Protocol (MCP) using JSON-RPC 2.0 over HTTP.

Endpoint

All MCP requests are sent to:

POST http://localhost:3000/mcp

MCP Methods

initialize

Initializes an MCP session.

Request:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": "1"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "capabilities": {
      "tools": true,
      "resources": true,
      "prompts": true
    }
  },
  "id": "1"
}

listTools

Lists available LinkedIn tools.

Request:

{
  "jsonrpc": "2.0",
  "method": "listTools",
  "params": {},
  "id": "2"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "profile_view",
        "description": "View a LinkedIn profile",
        "parameters": {
          "type": "object",
          "properties": {
            "profileUrl": {
              "type": "string",
              "description": "URL of the LinkedIn profile to view"
            }
          },
          "required": ["profileUrl"]
        }
      },
      // Additional tools...
    ]
  },
  "id": "2"
}

executeTool

Executes a LinkedIn tool.

Request:

{
  "jsonrpc": "2.0",
  "method": "executeTool",
  "params": {
    "name": "profile_search",
    "parameters": {
      "keywords": "software engineer",
      "location": "San Francisco",
      "limit": 5
    }
  },
  "id": "3"
}

Response:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "name": "John Doe",
      "title": "Senior Software Engineer",
      "location": "San Francisco Bay Area",
      "profileUrl": "https://www.linkedin.com/in/johndoe"
    },
    // Additional results...
  ],
  "id": "3"
}

listResources

Lists available LinkedIn resources.

Request:

{
  "jsonrpc": "2.0",
  "method": "listResources",
  "params": {},
  "id": "4"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "resources": [
      {
        "uri": "linkedin:profile",
        "description": "Current LinkedIn profile information"
      },
      // Additional resources...
    ]
  },
  "id": "4"
}

readResource

Reads a LinkedIn resource.

Request:

{
  "jsonrpc": "2.0",
  "method": "readResource",
  "params": {
    "uri": "linkedin:profile",
    "parameters": {
      "profileUrl": "https://www.linkedin.com/in/johndoe"
    }
  },
  "id": "5"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": "...",
    "metadata": {
      "contentType": "application/json"
    }
  },
  "id": "5"
}

listPrompts

Lists available LinkedIn prompt templates.

Request:

{
  "jsonrpc": "2.0",
  "method": "listPrompts",
  "params": {},
  "id": "6"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "prompts": [
      {
        "name": "connection_request",
        "description": "Template for LinkedIn connection requests"
      },
      // Additional prompts...
    ]
  },
  "id": "6"
}

getPrompt

Gets a LinkedIn prompt template.

Request:

{
  "jsonrpc": "2.0",
  "method": "getPrompt",
  "params": {
    "name": "connection_request"
  },
  "id": "7"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "template": "Hi {{name}},\n\nI came across your profile and would like to connect. {{reason}}\n\nLooking forward to connecting,\n{{your_name}}",
    "parameters": {
      "name": {
        "type": "string",
        "description": "Recipient's name"
      },
      "reason": {
        "type": "string",
        "description": "Reason for connecting"
      },
      "your_name": {
        "type": "string",
        "description": "Your name"
      }
    }
  },
  "id": "7"
}

LinkedIn Functionality

Profile Management

View Profile

Retrieves detailed information about a LinkedIn profile.

Tool: profile_view

Parameters:

• profileUrl: URL of the LinkedIn profile to view

Returns:

• Profile information including name, title, location, about, experiences, education, and skills

Search Profiles

Searches for LinkedIn profiles based on keywords and filters.

Tool: profile_search

Parameters:

• keywords: Keywords to search for
• location: Location filter (optional)
• limit: Maximum number of results to return (optional)

Returns:

• List of profile results with basic information

Connection Management

Send Connection Request

Sends a connection request to a LinkedIn profile.

Tool: connection_send

Parameters:

• profileUrl: URL of the LinkedIn profile to connect with
• message: Optional message to include with the request

Returns:

• Result of the connection request

List Connections

Lists your LinkedIn connections.

Tool: connection_list

Parameters:

• limit: Maximum number of connections to return (optional)

Returns:

• List of connections with name, occupation, and profile URL

List Pending Requests

Lists pending connection requests.

Tool: connection_pending

Parameters:

• limit: Maximum number of pending requests to return (optional)

Returns:

• List of pending connection requests

Messaging

Send Message

Sends a message to a LinkedIn connection.

Tool: message_send

Parameters:

• profileUrl: URL of the LinkedIn profile to message
• message: Message content to send

Returns:

• Result of the message send operation

List Conversations

Lists LinkedIn conversations.

Tool: message_list

Parameters:

• limit: Maximum number of conversations to return (optional)

Returns:

• List of conversations with participants, preview, and time

Read Conversation

Reads a LinkedIn conversation history.

Tool: message_read

Parameters:

• conversationUrl: URL of the conversation to read
• limit: Maximum number of messages to return (optional)

Returns:

• Conversation history with messages

Post Management

Create Post

Creates a new LinkedIn post.

Tool: post_create

Parameters:

• content: Post content
• visibility: Post visibility (connections, public, anyone)

Returns:

• Result of the post creation

Like Post

Likes a LinkedIn post.

Tool: post_like

Parameters:

• postUrl: URL of the LinkedIn post to like

Returns:

• Result of the like operation

Comment on Post

Comments on a LinkedIn post.

Tool: post_comment

Parameters:

• postUrl: URL of the LinkedIn post to comment on
• comment: Comment content

Returns:

• Result of the comment operation

Share Post

Shares a LinkedIn post.

Tool: post_share

Parameters:

• postUrl: URL of the LinkedIn post to share
• comment: Optional comment to add with the share

Returns:

• Result of the share operation

Job Management

Search Jobs

Searches for jobs on LinkedIn.

Tool: job_search

Parameters:

• keywords: Keywords to search for
• location: Location filter (optional)
• datePosted: Date posted filter (optional: 'past_24h', 'past_week', 'past_month')
• limit: Maximum number of results to return (optional)

Returns:

• List of job results

View Job

Views job details on LinkedIn.

Tool: job_view

Parameters:

• jobUrl: URL of the LinkedIn job to view

Returns:

• Job details including title, company, location, description, and requirements

Apply for Job

Applies for a job on LinkedIn (if Easy Apply is available).

Tool: job_apply

Parameters:

• jobUrl: URL of the LinkedIn job to apply for

Returns:

• Result of the application attempt

n8n Integration

Installing the MCP Nodes

1. In your n8n instance, go to Settings > Community Nodes
2. Install "n8n-nodes-mcp"

Configuring the MCP Client Node

1. Add an "MCP Client" node to your workflow
2. Create new credentials:
   • Connection Type: HTTP Transport
   • Server URL: http://localhost:3000/mcp (adjust for your server)
   • Authentication: None (or configure as needed)

Example Workflows

Profile Search and Processing

This workflow searches for LinkedIn profiles and processes each result:

1. Trigger Node: Schedule or manual trigger
2. MCP Client Node:
   • Operation: Execute Tool
   • Tool: profile_search
   • Parameters:
     • keywords: "software engineer"
     • location: "San Francisco"
     • limit: 5
3. Iterator Node: Process each profile
4. MCP Client Node:
   • Operation: Execute Tool
   • Tool: profile_view
   • Parameters:
     • profileUrl: Current item's profileUrl
5. Set Node: Format the data as needed
6. Action Node: Store or process the data

Automated Connection Requests

This workflow sends connection requests to profiles from a search:

1. Trigger Node: Schedule or manual trigger
2. MCP Client Node:
   • Operation: Execute Tool
   • Tool: profile_search
   • Parameters:
     • keywords: "hiring manager"
     • location: "New York"
     • limit: 3
3. Iterator Node: Process each profile
4. Function Node: Generate personalized message
5. MCP Client Node:
   • Operation: Execute Tool
   • Tool: connection_send
   • Parameters:
     • profileUrl: Current item's profileUrl
     • message: Generated message
6. Slack Node: Send notification of sent requests

For more example workflows, see the n8n workflow example.

Deployment Guide

Local Deployment

To run the server locally:

./start.sh

Docker Deployment

To deploy using Docker:

docker build -t linkedin-mcp-server .
docker run -p 3000:3000 --env-file .env linkedin-mcp-server

Proxmox LXC Container Deployment

For detailed instructions on deploying as an LXC container on Proxmox, see the Proxmox Deployment Guide.

Testing

Running Tests

To run the basic tests:

./test.sh

Testing with n8n

For detailed instructions on testing with n8n, see the Testing Guide.

Troubleshooting

Common Issues

Authentication Failures

Symptoms:

• "LinkedIn security checkpoint detected" error
• "CAPTCHA detected during login" error

Solutions:

• Verify your LinkedIn credentials in the .env file
• Log in to LinkedIn manually in a regular browser to resolve any security checkpoints
• Consider using a proxy to avoid detection
• Reduce the frequency of requests to avoid triggering security measures

Rate Limiting

Symptoms:

• "Too many requests" errors
• Operations failing after extended use

Solutions:

• Adjust the MAX_REQUESTS_PER_HOUR setting in the .env file
• Implement delays between operations
• Use a proxy rotation service for high-volume operations

Browser Automation Issues

Symptoms:

• "Element not found" errors
• Unexpected page structure

Solutions:

• LinkedIn may have updated their UI; check for selector changes
• Increase timeouts for slow connections
• Set HEADLESS=false temporarily to debug visually

Logs

Check the following log files for troubleshooting:

• error.log: Error messages
• combined.log: All server logs
• linkedin-*.log: Specific LinkedIn service logs

Security Considerations

Credential Management

• Store LinkedIn credentials securely
• Use environment variables or a secrets manager
• Never commit credentials to version control

Rate Limiting

• Respect LinkedIn's usage policies
• Implement appropriate rate limiting
• Monitor for unusual activity

Network Security

• Use HTTPS for production deployments
• Implement proper authentication for the MCP server
• Consider using a VPN or proxy for LinkedIn connections

Limitations and Compliance

LinkedIn Terms of Service

This tool interacts with LinkedIn's web interface and should be used in compliance with LinkedIn's Terms of Service. Be aware that:

• LinkedIn may change their UI at any time, potentially breaking functionality
• Excessive automation may lead to account restrictions
• Some actions may be against LinkedIn's terms of service

Legal Considerations

• This tool is provided for educational and legitimate business purposes only
• Users are responsible for ensuring their use complies with applicable laws and terms of service
• Data scraping and automation may be subject to legal restrictions in some jurisdictions

Technical Limitations

• Complex LinkedIn interactions may not be fully automated
• Some features may require manual intervention
• Performance may be affected by network conditions and LinkedIn's responsiveness

Conclusion

The LinkedIn MCP Server provides a powerful way to integrate LinkedIn functionality with n8n workflows without requiring official API access. By following this documentation, you should be able to install, configure, and use the server effectively for your automation needs.

For further assistance or to report issues, please contact the project maintainers.