# LinkedIn Ops

No more manual LinkedIn scrolling. Search for jobs on LinkedIn blazing fast with your favorite coding agent, including Claude Code, Codex, and more. Then manage them using the web frontend.

[![MCP](https://img.shields.io/badge/MCP-7C3AED?style=flat-square)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-7C3AED?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Playwright](https://img.shields.io/badge/Playwright-7C3AED?style=flat-square&logo=playwright&logoColor=white)](https://playwright.dev/)
[![React](https://img.shields.io/badge/React-7C3AED?style=flat-square&logo=react&logoColor=white)](https://react.dev/)
[![Express](https://img.shields.io/badge/Express-7C3AED?style=flat-square&logo=express&logoColor=white)](https://expressjs.com/)
[![Vite](https://img.shields.io/badge/Vite-7C3AED?style=flat-square&logo=vite&logoColor=white)](https://vitejs.dev/)
[![Tailwind%20CSS](https://img.shields.io/badge/Tailwind_CSS-7C3AED?style=flat-square&logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)

---

## Overview

**LinkedIn Ops** is a Model Context Protocol (MCP) server that lets your AI assistant (Claude Code, Codex, Claude Desktop, Cursor, or any MCP-compatible client) search LinkedIn for job posts, save them locally, and manage them through a React dashboard.

Job opportunities often appear in LinkedIn posts before they hit traditional job boards. This tool helps you catch them early.

### How it works

1. **Authenticate** — A browser window opens for you to log into LinkedIn. Session cookies are saved locally for future use.
2. **Search** — Your AI assistant scrapes LinkedIn posts by keyword using Chromium. The browser is visible by default, with an optional headless mode.
3. **Store** — All posts are saved to a local SQLite database. Nothing leaves your machine.
4. **Dashboard** — A React web UI at `http://localhost:4327` lets you browse, filter, and track posts visually.
5. **Dual control** — Manage posts through natural language AI commands or point-and-click in the dashboard. Changes sync both ways in real time.

---

## Project Structure

```
./app/
├── lib/              # Shared: auth, database, utilities
├── client/           # React dashboard (Vite + TailwindCSS)
└── servers/
    ├── mcp/          # MCP server entry point + tools
    └── api/          # Express REST API (serves dashboard)
```

---

## Installation

### Install from source

```bash
git clone https://github.com/yasir-ali/linkedin-ops.git
cd linkedin-ops
npm run install:all
npm run build
```

For local development, run `npm link` after the build if you want to invoke your checkout with the `linkedin-ops` command. This creates a global symlink on your machine; it does not publish anything to npm.

### Claude Code

This repository includes a project-level [`.mcp.json`](.mcp.json) for Claude Code. After cloning, replace its `args[0]` value with the absolute path to **your own clone**:

```json
{
  "mcpServers": {
    "linkedin-ops": {
      "command": "node",
      "args": ["/absolute/path/to/linkedin-ops/dist/servers/mcp/index.js"]
    }
  }
}
```

Restart Claude Code or start a new chat in the project. The shared [`.claude/settings.json`](.claude/settings.json) contains project settings; `.claude/settings.local.json` is intentionally ignored because it is machine-specific.

### Codex

This repository includes a project-scoped [`.codex/config.toml`](.codex/config.toml). Replace the path in `args` with the absolute path to **your own clone**, then reopen the project or start a new Codex chat.

In Codex, use `/mcp` to confirm that `linkedin-ops` is connected. If the project configuration is not loaded, add the same command manually under **Settings → MCP servers** as a **STDIO** server:

```text
Command: node
Path: /absolute/path/to/linkedin-ops/dist/servers/mcp/index.js
```

---

## MCP Tools

| Tool | Description | Example prompt |
| ---- | ----------- | -------------- |
| `auth` | Sign in, check the LinkedIn session, or clear saved credentials. | “Check LinkedIn auth status” |
| `search_posts` | Search LinkedIn posts and save new results locally. | “Find React developer posts, 5 pages, headless” |
| `manage_posts` | Read, count, or delete stored posts. Supports keyword, text, ID, applied, saved, limit, and offset filters. | “Show posts I haven't applied to” |
| `dashboard_filters` | Read or update filters shared with the dashboard. | “Show only unapplied posts” |
| `start_dashboard` | Open the local dashboard at `http://localhost:4327`. | “Open the dashboard” |
| `stop_dashboard` | Stop the local dashboard server. | “Stop the dashboard” |
| `debug_page` | Inspect a LinkedIn page’s DOM while using the saved session. | “Inspect the LinkedIn search results page structure” |

---

## Dashboard

Run manually if needed:

```bash
npm run dev    # start dashboard at http://localhost:4327
npm run kill   # kill whatever is holding port 4327
```

Features:

- Table and card views
- Filter by keyword, date, status, and saved state
- Mark posts as interested, applied, not interested, or saved
- Refreshes automatically every 3 seconds

---

## Data Storage

Data remains local. Nothing is sent to external servers.

| Platform    | Location                  |
| ----------- | ------------------------- |
| Windows     | `%APPDATA%\linkedin-mcp\` |
| macOS/Linux | `~/.linkedin-mcp/`        |


---

## Scripts

| Command             | Description                       |
| ------------------- | --------------------------------- |
| `npm run build`     | Full build (TypeScript + React)   |
| `npm run dev`       | Start dashboard at localhost:4327 |
| `npm run kill`      | Kill dashboard process            |
| `npm run clean`     | Delete dist/                      |
| `npm run typecheck` | TypeScript check without building |

---

## License

MIT — see [LICENSE](LICENSE) for details.