Linkedin Posts Hunter MCP Server

🚀 LinkedIn Posts Hunter MCP Server

Automate LinkedIn job post searching and tracking with AI-powered assistance

🚀 Quick Start

LinkedIn Posts Hunter MCP Server is a powerful tool that enables you to automate LinkedIn job post search and management with the help of an AI assistant. Here's how to get started:

1. Installation: Follow the installation steps in the "📦 Installation" section.
2. Authentication: Use the auth tool to log in to your LinkedIn account.
3. Searching: Use the search_posts tool to find relevant job posts.
4. Managing: Use the manage_posts tool to manage the scraped posts.
5. Visualizing: Launch the React dashboard with the start_viewer tool to visualize and manage your posts.

✨ Features

• Automated Search: Automate LinkedIn job post search and management through your AI assistant.
• Local Data Storage: All scraped posts are saved to a local SQLite database on your machine, ensuring data privacy.
• Visual Interface: A React dashboard provides a user-friendly interface to visualize and manage your scraped posts.
• Dual Control: Manage posts through either the React UI or MCP tools, offering flexibility.

📦 Installation

Prerequisites

• Node.js 18 or higher
• npm (comes with Node.js)
• A LinkedIn account
• Cursor IDE or Claude Desktop

Method 1: Using mcp.json Configuration (Recommended) ⭐

This is the most reliable and widely-supported installation method.

1. Install globally:

npm install -g linkedin-posts-hunter-mcp

2. Add to your MCP configuration:
   • For Cursor IDE: Open or create mcp.json at:
     • macOS/Linux: ~/.cursor/mcp.json
     • Windows: %USERPROFILE%\.cursor\mcp.json (typically C:\Users\YourName\.cursor\mcp.json) Add this configuration:

{
  "mcpServers": {
    "linkedin-posts-hunter-mcp": {
      "command": "linkedin-posts-hunter-mcp"
    }
  }
}

• For Claude Desktop: Open or create claude_desktop_config.json at:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json Add this configuration:

{
  "mcpServers": {
    "linkedin-posts-hunter-mcp": {
      "command": "linkedin-posts-hunter-mcp"
    }
  }
}

3. Restart your MCP client (Cursor or Claude Desktop)

Method 2: Local Development Setup

For developers who want to modify the code or contribute:

1. Clone and install dependencies:

git clone https://github.com/kevin-weitgenant/LinkedIn-Posts-Hunter-MCP-Server.git
cd LinkedIn-Posts-Hunter-MCP-Server
npm run install:all
npm run build

2. Add to your MCP configuration:
   • For Cursor IDE (mcp.json):

{
  "mcpServers": {
    "linkedin-posts-hunter-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/LinkedIn-Posts-Hunter-MCP-Server/build/index.js"
      ],
      "cwd": "/absolute/path/to/LinkedIn-Posts-Hunter-MCP-Server"
    }
  }
}

• For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "linkedin-posts-hunter-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/LinkedIn-Posts-Hunter-MCP-Server/build/index.js"
      ],
      "cwd": "/absolute/path/to/LinkedIn-Posts-Hunter-MCP-Server"
    }
  }
}

⚠️ Important: Replace /absolute/path/to/LinkedIn-Posts-Hunter-MCP-Server with your actual project path. 3. Restart your MCP client to load the server.

💻 Usage Examples

Job Search Workflow Example

1. Authenticate with LinkedIn:

User: "Authenticate my LinkedIn account"
AI: Opens a browser for you to log in, saves credentials

2. Search for opportunities:

User: "Search LinkedIn for 'Senior TypeScript Developer remote' jobs"
AI: Searches LinkedIn, extracts post details, saves to database

3. Visual exploration:

User: "Open the post viewer"
AI: Launches React dashboard(where you can see the scraped posts) at http://localhost:5174

4. Filter and manage:

User: "Remove posts that aren't about job opportunities"
AI: Reads database, filters and displays only job-related posts

User: "Show only senior-level positions" 
AI: Queries database for posts containing "senior", "lead", "principal"

User: "Show posts about React or Vue.js positions"
AI: Searches database and displays matching posts

5. Track applications:

User: "Mark posts 5, 7, and 12 as applied"
AI: Updates the database and confirms

📚 Documentation

📖 Overview

LinkedIn Posts Hunter MCP is a Model Context Protocol (MCP) server that provides tools for automating LinkedIn job post search and management through your AI assistant (Claude Desktop, Cursor, or other MCP-compatible clients).

Why LinkedIn Posts? Job opportunities often appear in LinkedIn posts first, before they're posted on traditional job boards. By monitoring LinkedIn posts, you can discover opportunities earlier and get a competitive advantage in your job search.

How it works:

1. Authentication & Scraping
   • The MCP server exposes a Playwright-based tool that your AI assistant can invoke to automate browser interactions with LinkedIn.
   • First-time use requires logging into LinkedIn through a browser window to capture session cookies.
   • These cookies are stored locally on your computer for persistent authentication.
   • Once authenticated, your AI assistant can call the search tool with keywords (either from your conversation or suggested by the AI) to scrape job posts.
2. Local Data Storage
   • All scraped posts are saved to a local SQLite database on your machine.
   • The database stores post content, metadata (author, dates, engagement metrics), and tracking info (whether you've applied).
   • Your data never leaves your computer.
3. Visual Interface
   • A separate tool launches a React dashboard that renders the scraped posts from your local database.
   • Visualize all your scraped posts in table or card views with profile images and engagement metrics.
   • Track your applications by marking posts as "applied" or "saved for later" directly in the UI.
   • Quick actions let you filter, sort, and manage posts with point-and-click simplicity.
   • Changes made in the React app are written to the local database. And changes made through MCP commands are reflected in the UI.
4. Dual Control
   • You can manage posts through either the React UI or through MCP tools like manage_posts and viewer_filters.
   • The React app updates via polling, so changes made through MCP commands are reflected in the UI.
   • This gives you flexibility: use natural language commands with your AI assistant, or point-and-click in the dashboard.

🎬 Video Demo

https://github.com/user-attachments/assets/93f32db4-9ecf-4438-889f-ebe95b5b17e9

📹 Watch Walkthrough

Watch the complete workflow from authentication to post management

🎨 Diagram

🛠️ Available Tools

This MCP server exposes 6 tools that can be called from your AI assistant:

1. auth: Manage LinkedIn authentication with persistent session storage.
   • Parameters:
     • action: "authenticate" | "status" | "clear"
     • force_reauth: boolean (optional)
   • Usage:

"Authenticate my LinkedIn account"
"Check LinkedIn auth status"
"Clear my LinkedIn credentials"

2. search_posts: Search LinkedIn posts by keywords and save results to the database.
   • Parameters:
     • keywords: string (e.g., "Python developer remote")
     • pagination: number (1 - 10, default: 3)
     • headless: boolean (default: false) - show the browser window (default: false)
   • Usage:

"Search LinkedIn for 'AI engineer' jobs"
"Find posts about 'React developer' with 5 pages"

3. manage_posts: Read, update, or delete posts from the database with advanced filtering.
   • Parameters:
     • action: "read" | "update" | "delete"
     • ids: number[] (optional)
     • search_text: string (optional)
     • date_from: string (YYYY - MM - DD, optional)
     • date_to: string (YYYY - MM - DD, optional)
     • applied: boolean (optional)
     • limit: number (1 - 50, default: 10)
     • new_description: string (for updates)
     • new_keywords: string (for updates)
     • new_applied: boolean (for updates)
   • Usage:

"Show me posts I haven't applied to yet"
"Delete all posts that arent about job opportunities"
"Delete all posts that are only about senior-level positions"

4. viewer_filters: Control the React UI filters programmatically from the AI conversation.
   • Parameters:
     • keyword: string (optional)
     • applied_status: "all" | "applied" | "not-applied" (optional)
     • start_date: string (YYYY - MM - DD, optional)
     • end_date: string (YYYY - MM - DD, optional)
     • ids: string (comma-separated, optional)
     • reset: boolean (optional)
   • Usage:

"Filter to show only unapplied posts"
"Show posts from this week"
"Reset all filters"

5. start_viewer: Launch the React dashboard in your browser.
   • Usage:

"Open the LinkedIn post viewer"
"Start the dashboard"

6. stop_viewer: Stop the running Vite development server.
   • Usage:

"Close the viewer"
"Stop the dashboard"

📁 Data Storage Locations

All your LinkedIn data is stored locally on your computer in the following directories:

🎨 React Dashboard Features

The built-in web viewer (start_viewer) provides:

• 🔄 Real-time Updates: Filter state syncs between UI and MCP commands.
• ✅ Quick Actions: Mark posts as applied directly from the UI.
• 🎴 Card View: Visual cards with profile images and engagement metrics.
• 📊 Table View: Sortable columns with all post metadata.
• 🔍 Filtering: By keyword, date range, applied status, and IDs.
• 💅 Modern Design: Built with React, TypeScript, TailwindCSS, and Vite.

🔧 Technical Details

The scraping process could be optimized for better performance, and the UI could be improved to enhance the user experience. However, the current version is already somewhat useful.

📄 License

ISC

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

🚀 Project Status

This is an experimental project, quick and dirty. The scraping could definitely be optimized to be faster, and the UI could be improved as well. But as it is, it's already somewhat useful. Feel free to contribute.