insaight
Persists research briefs to a configured Notion page.
insaight
LinkedIn prospect intelligence inside Claude — it automates the research, not the outreach.
Insaight scrapes public LinkedIn data via Apify, stores it in local SQLite, and hands it to Claude through an MCP server and eight skills. Data flows in once, then stays on your machine — repeat questions hit SQLite, not Apify.
Architecture
graph LR
C["Claude Code / Desktop<br/>8 skills"] -->|MCP| S["insaight server<br/>18 tools"]
S --> DB[("SQLite<br/>~/.insaight/posts.db")]
S --> M["memory/<br/>style.md · playbook.md"]
S -->|fresh scrapes only| A["Apify<br/>LinkedIn actors"]Related MCP server: linkedin-engine
Install in 30 seconds
Prerequisite: uv and Python 3.11+. The plugin runs the MCP server with uvx, so without uv the tools never load.
curl -LsSf https://astral.sh/uv/install.sh | sh # skip if you already have uvThen, in Claude Code:
/plugin marketplace add spirosbax/insaight
/plugin install insaight@insaightAdd your Apify token (free tier works):
mkdir -p ~/.insaight && echo "APIFY_API_TOKEN=apify_api_..." >> ~/.insaight/.envRestart Claude Code and say "research Anthropic on LinkedIn". The plugin registers the MCP server and installs all eight skills; there is nothing to clone.
On the very first run,
uvxbuilds the server before it answers — give it a few seconds. If the insaight tools never appear, check thatuvis on yourPATH.
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"insaight": {
"command": "uvx",
"args": ["--from", "git+https://github.com/spirosbax/insaight@v0.2.0", "insaight"],
"env": { "APIFY_API_TOKEN": "apify_api_..." }
}
}
}Restart Claude Desktop, then add the skills under Settings → Skills → Add skills, selecting the SKILL.md files from this repo's skills/ directory.
git clone https://github.com/spirosbax/insaight.git && cd insaight
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest -q # hermetic — temp SQLite, no credentials
claude mcp add insaight -s user -- "$PWD/.venv/bin/insaight" # local checkout instead of uvxA checkout with a data/ directory uses it as INSAIGHT_HOME, keeping the dev database inside the repo (gitignored).
Skills
Eight skills that chain conversationally — each one's output feeds the next. They are plain Markdown with YAML frontmatter: easy to read, fork, and customize.
Skill | One line |
research-person | Intelligence brief on an individual: themes, decision-maker signals, outreach hooks, uncommon commonalities |
research-company | Company analysis from company posts + up to 3 C-level executives' posts, with a prospect score |
research-post | Mine a post's comment thread for warm leads, decision-makers, and competitor mentions |
draft-outreach | Cold DM + email, two variants each, using prior research + your learned style memory |
draft-post | LinkedIn post in your company's voice, styled on your own past posts (URL-to-post supported) |
track-outreach | Log sends and outcomes in the local ledger ("I sent it", "she replied", "mark as ghosted") |
reflect | Analyze outcomes, propose evidence-backed memory updates — applied only on your approval |
save-notion | Persist research briefs to your configured Notion page (optional, needs the Notion MCP) |
prospecting research company → draft outreach → save to Notion
person-first research person → draft outreach
qualification research company → read the prospect evaluation → pursue or passAn unedited Claude Code session: install, research Anthropic, find the right person, draft the DM, log the send.
The memory loop
draft → send → "I sent it" → logged (log_outreach)
→ "she replied" / "ghosted" → outcome recorded (record_outcome)
→ every N outcomes → reflection proposed (default 10; REFLECT_EVERY)
→ you approve → style.md + playbook.md updatedOutcomes are logged because you say so — Insaight never reads your inbox. Every playbook claim carries its evidence ("question hooks: 4/9 replied vs statement hooks: 1/8"), and below n=10 a pattern is a hypothesis, not a rule. Nothing is written to memory without your approval. The ledger also powers prior-contact warnings ("you messaged this person 3 weeks ago — ghosted") whenever you research or draft.
Tool | Purpose |
| Discover tracked companies and personal profiles |
| Fetch fresh posts for any LinkedIn URL (Apify) |
| Fetch company employees and leadership (Apify, Short or Full mode) |
| Enrich one person with full profile: experience, education, skills, volunteer, languages |
| Token-cheap index: metadata + 150-char snippet |
| Full content for selected posts by URN (max 20 per call) |
| Full-text keyword search across stored posts |
| Query stored employees/leadership (instant, free) |
| Fetch a post's comment thread with author info (Apify) |
| Query stored comments for a post, ranked by likes |
| Database overview: counts, date range, categories |
| Record a sent message in the ledger (flags prior contact) |
| Record replied / positive / meeting / ghosted; flags when reflection is due |
| Query the ledger: prior-contact checks, pending sends, history |
| Reply-rate breakdown by hook type, variant, and channel |
| Read the learned style guide + strategy playbook |
| Rewrite a memory file (only after an approved reflection) |
| Read your Notion pages + company config from |
Reading pattern: list_posts returns ~80 tokens per post; scan snippets, then get_posts only the interesting ones.
Everything is under ~/.insaight/ (override with INSAIGHT_HOME):
~/.insaight/
.env APIFY_API_TOKEN, ANTHROPIC_API_KEY (optional), REFLECT_EVERY
config.md Notion pages + company config (read by get_config)
posts.db SQLite: posts, people, comments, outreach ledger
memory/ style.md + playbook.md (written by the reflect skill)Actor | Scrapes | Approx. cost |
| Company or personal posts | ~$1.50 / 1k posts |
| Employees and leadership |
|
| Single-profile enrichment |
|
| Comment threads | see actor page |
Rates as published at time of writing — check the actor pages for current pricing.
A standalone CLI for batch work outside Claude (insaight-cli in a dev install, or uvx --from git+https://github.com/spirosbax/insaight insaight-cli):
insaight-cli scrape --accounts config/accounts.txt # scrape tracked accounts (--no-categorize skips the Anthropic API)
insaight-cli stats # database overview
insaight-cli export --format csv --output posts.csv # export to CSV or JSONData, privacy & terms
Everything stays local: posts, people, the outreach ledger, and learned memory live in SQLite and Markdown on your machine, and nothing is sent anywhere except your own Apify/Anthropic/Notion accounts. No inbox access — outcomes exist because you reported them. Insaight fetches public LinkedIn data through third-party Apify actors; automated collection may conflict with LinkedIn's Terms of Service, and you are responsible for how you use this tool. Keep volumes reasonable and respect the people behind the profiles.
License
Available Tools
18 toolsget_configA
Return the user's insaight config (Notion pages, company name/slug).
Skills call this first to learn where to save research and whose voice to write in. The file lives at <INSAIGHT_HOME>/config.md (default ~/.insaight/config.md); it is created with placeholder values on first call. If values are still placeholders, ask the user to edit the file.
Inputs: no named parameters. Returns: result
get_memoryA
Read the distilled outreach memory: the style guide and the strategy playbook. The draft-outreach and draft-post skills should read THIS (a few hundred tokens) instead of re-deriving style from raw history.
Returns both files plus whether they've been learned yet and the reflection state. If not yet learned, fall back to reading recent outreach (list_outreach) or the Notion log, and suggest running insaight-reflect once a few outcomes are logged.
Inputs: no named parameters. Returns: result
get_outreach_statsA
Reply-rate breakdown of the outreach ledger: totals plus per-hook_type, per-variant, and per-channel rates (pending sends excluded from rates), and the current reflection state.
This is the evidence source for the insaight-reflect skill — cite these counts (e.g. "question hooks: 4/9 replied") in any proposed memory update.
Inputs: no named parameters. Returns: result
get_postsA
Fetch full content for a specific list of posts by their URNs.
Use this after list_posts() to read only the posts you actually need. Accepts up to 20 URNs per call. URNs come from the 'urn' field in list_posts results.
Args: urns: List of post URN strings to fetch (max 20).
Inputs: urns (required). Returns: result
get_statsA
Return a DB-wide overview: total posts, accounts, date range, category breakdown. Useful for a quick orientation before diving into posts.
Inputs: no named parameters. Returns: result
list_accountsA
List all tracked LinkedIn accounts (companies and profiles) in the database.
Returns each account's slug (short name), full URL, post count, and date of most recent post. ALWAYS call this first to discover what accounts are available and learn the correct slugs to use in other tools.
Inputs: no named parameters. Returns: result
list_commentsA
List stored comments for a post, ranked by likes desc then time.
Provide either post_urn (e.g. "urn:li:activity:7451209045283254272") or post_url (the full LinkedIn URL — the URN is extracted automatically).
Args: post_urn: Post URN. Use this OR post_url. post_url: Full LinkedIn post URL. The URN is extracted from it. limit: Max comments returned (default 100). min_likes: Only return comments with at least this many likes. include_replies: If False, only top-level comments are returned.
Inputs: limit, post_url, post_urn, min_likes, +1 more. Returns: result
list_outreachA
Query the outreach ledger, newest first. Use for prior-contact checks ("have I messaged this person?"), reviewing pending sends, or pulling recent messages for reflection.
Args: outcome: Filter: "pending" | "replied" | "positive" | "meeting" | "ghosted". Empty = all. target: Substring match on target URL, name, or company. limit: Max records (default 30, max 100). full: If True, include full message text (use for reflection); default False returns a 150-char snippet.
Inputs: full, limit, target, outcome. Returns: result
list_peopleA
List stored employees/leadership for a company from the local database.
This is instant (no Apify call). If the result is empty, call scrape_people() first to populate the database for this company.
Args: account: Slug (e.g. "acme-charging") or full LinkedIn company URL. Use list_accounts() to discover available slugs. role: Optional keyword to filter by — matched against name, headline, and job titles. Examples: "CEO", "founder", "sales", "engineer". Leave empty to return all stored people. limit: Max results to return (default 50).
Inputs: account (required), role, limit. Returns: result
list_postsA
Return a slim index of posts (metadata + 150-char snippet, NO full content).
Use this to survey what posts exist before deciding which ones to read in full via get_posts(). Fetching slim records first is far more token-efficient.
Args: account: Slug (e.g. "acme-charging") or full LinkedIn URL. Empty = all accounts. Use list_accounts() to find slugs. category: Filter by semantic category (e.g. "product", "hiring"). days_ago: Only posts from the last N days (0 = no limit). min_engagement: Only posts where likes+comments+shares >= this value. limit: Max posts to return (default 30, max 100).
Inputs: limit, account, category, days_ago, +1 more. Returns: result
log_outreachA
Record an outreach message the user actually SENT. Call this when the user says they sent a message ("I sent it", "log this outreach").
The stored ledger replaces a manual sent-log: it powers prior-contact checks, reply-rate stats, and the reflection loop that learns what works. The response includes any prior contact with the same target — surface that to the user if present.
Args: target_url: LinkedIn profile URL (or email address) of the recipient. message: The exact message text that was sent. target_name: Recipient's name (optional but recommended). company: Recipient's company (optional). channel: "dm" | "email" | "other" (default "dm"). variant: Which draft variant was sent: "warm" | "direct" | "follow-up" | free text. hook_type: Opening hook used: "question" | "statement" | "story" | "stat" | "commonality" | free text. Used for reply-rate breakdowns. notes: Anything worth remembering about this send (optional).
Inputs: message (required), target_url (required), notes, channel, +4 more. Returns: result
record_outcomeA
Record what happened to a sent outreach message. Call when the user says the target replied, booked a meeting, or went quiet.
Identify the record by outreach_id, OR by target_url (resolves to that target's most recent pending message).
The response includes reflection_due — when true, tell the user that enough outcomes have accumulated and offer to run the insaight-reflect skill.
Args: outreach_id: Row id returned by log_outreach() (preferred). target_url: Alternative lookup: the target's URL/email. outcome: "replied" | "positive" | "meeting" | "ghosted". (positive = reply with clear interest; meeting = call booked) reply_snippet: A short quote from the reply — evidence for reflection. notes: Optional context (e.g. "replied after the follow-up nudge").
Inputs: notes, outcome, target_url, outreach_id, +1 more. Returns: result
scrape_peopleA
Scrape and store company employees/leadership from LinkedIn via Apify.
Results are stored in the database so subsequent calls to list_people() are instant without any Apify cost. Run this once per company; re-run only when you need fresher data (people data is updated by upsert, not duplicated).
Args: url: Full LinkedIn company URL. Example: https://www.linkedin.com/company/acme-charging job_titles: Optional list of job titles to filter by on LinkedIn. Example: ["CEO", "Founder", "CTO", "Head of", "Director"] Leave empty to scrape all visible employees (up to max_items). max_items: Maximum number of profiles to fetch (default 50, max 200). For leadership only, use 10–20 with specific job_titles. full_mode: If True, uses Full profile scraper mode ($8/1k) to also fetch about, experience, education, skills, certifications, languages, volunteer, projects, recommendations. Default False (Short mode, $4/1k) which returns only name, headline, location, current role. Use True when you need commonality-mining data for outreach.
Inputs: url (required), full_mode, max_items, job_titles. Returns: result
scrape_person_profileA
Enrich ONE LinkedIn profile with full data (experience, education, skills, certifications, languages, volunteer, projects, recommendations, about).
Use this when you need commonality hooks for outreach — e.g. overlapping past employers, shared schools, mutual volunteer work, common languages. The result is upserted into the people table, so existing short-mode data is preserved and the extended fields are merged in.
Uses harvestapi/linkedin-profile-scraper ($4/1k without email, $10/1k with).
Args: url: Full LinkedIn profile URL. Example: https://www.linkedin.com/in/williamhgates with_email: If True, also runs email search ($10/1k instead of $4/1k). Default False. company_url: Optional LinkedIn company URL to associate this person with. If empty, uses the person's current company from Apify (or falls back to the profile URL itself).
Inputs: url (required), with_email, company_url. Returns: result
scrape_post_commentsA
Scrape and store comments on a LinkedIn post via Apify.
Use this to research who is engaging with a specific post — comments often reveal warm leads, decision-makers, competitor mentions, and pain points.
Args: post_url: Full LinkedIn post URL. Either /posts/_-activity-XXX or /feed/update/urn:li:activity:XXX form is accepted. max_items: Max comments (and replies) to fetch (default 50, capped at 200). include_replies: If True, also fetch nested replies (default True). profile_mode: "short" (free profile data attached to each comment) or "main" ($0.002/profile, more author detail). Default "short".
Inputs: post_url (required), max_items, profile_mode, include_replies. Returns: result
scrape_profileA
Scrape fresh LinkedIn posts from any company or personal profile URL via Apify and store them in the database. Works for profiles NOT yet in the database.
Use this when the user asks about a LinkedIn account that list_accounts() doesn't return, or when they want up-to-date posts for an existing account.
Requires APIFY_API_TOKEN to be set in the project .env file.
Args: url: Full LinkedIn URL of the company or person to scrape. Examples: https://www.linkedin.com/company/acme-charging https://www.linkedin.com/in/williamhgates max_posts: Maximum number of posts to fetch (default 30, max 100).
Inputs: url (required), max_posts. Returns: result
search_postsA
Full-text search across post content (case-insensitive keyword/phrase match).
Returns full content for matched posts only — use for targeted lookups rather than open-ended browsing (use list_posts for that).
Args: query: Word or phrase to search for in post text. account: Slug or full URL to restrict search to one account (optional). days_ago: Only search posts from the last N days (0 = no limit). limit: Max results (default 15, max 50).
Inputs: query (required), limit, account, days_ago. Returns: result
update_memoryA
Rewrite a memory file. ONLY call this after the user has approved the proposed content (the insaight-reflect skill shows a draft first — never overwrite memory silently).
Args: kind: "style" or "playbook". content: The full new Markdown content of the file (not a diff). mark_reflection_done: Set True on the LAST update of a reflection run — resets the outcomes-since-reflection counter.
Inputs: kind (required), content (required), mark_reflection_done. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each major workflow—accounts, posts, people, comments, outreach, and memory—has mostly distinct tools with clear descriptions. The main risk is scrape_profile versus scrape_person_profile, since both mention profiles, and get_stats versus get_outreach_stats could cause momentary confusion, though their descriptions disambiguate them well.
Tool names follow a consistent snake_case verb_noun pattern with list_* for reading stored data, scrape_* for fetching fresh data, and get_* for direct retrieval. The pair scrape_profile/scrape_person_profile is slightly confusing because 'profile' is used to mean both a LinkedIn account's posts and an individual person's full profile, but overall the naming is predictable.
Eighteen tools is on the heavier side, but the server genuinely covers multiple related domains: LinkedIn post scraping, people research, comment scraping, outreach tracking, memory, and configuration. Each tool has a distinct job, so the count feels reasonable for the stated scope rather than padded.
The core lifecycle is well covered: discover accounts, scrape and read posts, search content, scrape people and comments, log outreach, record outcomes, and update memory. Minor gaps include no delete/edit path for accounts, people, or outreach records, and no direct get-person-by-URL tool for retrieving enriched profile details after scrape_person_profile.
Maintenance
Related MCP Connectors
LinkedIn outreach in Claude or ChatGPT: campaign stats, replies, leads, drafts. Never sends.
LinkedIn outreach from Claude with a human veto: review, approve and send drafts, triage replies.
LinkedIn outreach from Claude: invites under safe caps, follow-ups, replies and inbox triage.
Cold email infrastructure — campaigns, prospects, mailbox health and replies via Claude.
Related MCP Servers
- AlicenseBqualityDmaintenanceConnects Claude Desktop to LinkedIn's data layer for AI-powered networking, enabling profile research, content creation and scheduling, engagement automation, analytics tracking, and messaging through natural language.48546MIT
- AlicenseNot gradedqualityDmaintenanceEnables running the entire LinkedIn sales motion inside Claude Code, including content creation, audience warming, outreach, and booking calls.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables B2B prospecting from natural language: detect buying signals, score leads against ICP, enrich decision-makers, and draft personalized outreach messages via Claude.3MIT
- AlicenseAqualityBmaintenanceAI agent for LinkedIn outreach: finds the right people, writes in your voice, follows up, replies. Six campaign goals: sell a product or service, find a job, hire people, find partners or investors, find a vendor, research interviews. Campaigns stay drafts until you launch them.224,076 PyPI13MIT