harvestapi-mcp

MCP server for HarvestAPI — LinkedIn profiles, companies, posts, jobs, leads, ads, groups, and platform account data over the Model Context Protocol (stdio).

All 25 tools are read-only. No message sending, no connection automation, no billing mutations.

Legal / Ethical Notice

This server is a thin wrapper over the HarvestAPI LinkedIn-data API. You are responsible for complying with LinkedIn's Terms of Service, HarvestAPI's Terms, and applicable data-protection laws (GDPR, etc.) when using LinkedIn-sourced data. Do not use harvested data to spam, harass, or violate privacy. The maintainers provide no warranty and accept no liability for how you use the tool.

HarvestAPI is a third-party scraping/enrichment service — it is not affiliated with LinkedIn.

Related MCP server: linkedin-mcp-pro

Prerequisites

• Node.js 20+

• A HarvestAPI key — get one at https://harvestapi.io/admin/api-keys

Install

git clone https://github.com/Hassan220022/harvestapi-mcp
cd harvestapi-mcp
npm ci
npm run build

Or run without cloning (after npm publish or via npx from the repo):

npx --yes github:Hassan220022/harvestapi-mcp

Environment

Copy .env.example to .env for local dev — but do not commit .env.

cp .env.example .env
# edit .env

Configure

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "harvestapi": {
      "command": "node",
      "args": ["/absolute/path/to/harvestapi-mcp/dist/index.js"],
      "env": {
        "HARVESTAPI_KEY": "your_key_here"
      }
    }
  }
}

Generic MCP (any stdio client)

{
  "command": "node",
  "args": ["/path/to/harvestapi-mcp/dist/index.js"],
  "env": { "HARVESTAPI_KEY": "your_key_here" }
}

Using npx (no local build)

{
  "mcpServers": {
    "harvestapi": {
      "command": "npx",
      "args": ["-y", "github:Hassan220022/harvestapi-mcp"],
      "env": { "HARVESTAPI_KEY": "your_key_here" }
    }
  }
}

Tools

25 tools, all harvest_*. Every tool maps to a verified HarvestAPI endpoint — see docs/tool-mapping.md and docs/harvestapi-endpoint-inventory.json.

Intentionally excluded (5 endpoints): accept-connection, send-connection, send-message, received-connections, sent-connections — they automate LinkedIn user actions. See tool-mapping.

Examples

Profile lookup

{ "tool": "harvest_get_profile", "arguments": { "publicIdentifier": "williamhgates" } }

Profile with enrichment flags

{ "tool": "harvest_get_profile", "arguments": { "url": "https://www.linkedin.com/in/williamhgates", "findEmail": "true", "skipSmtp": "true" } }

Company

{ "tool": "harvest_get_company", "arguments": { "universalName": "google" } }

Search profiles

{ "tool": "harvest_search_profiles", "arguments": { "search": "staff engineer", "currentCompany": "google", "page": "1" } }

Post comments

{ "tool": "harvest_get_post_comments", "arguments": { "post": "https://www.linkedin.com/posts/.../..." } }

Error & Rate-Limit Behavior

HarvestAPI has no per-minute rate limit; concurrency limits are per plan (Free 1, Starter 5, Basic 10, Pro 20, Business 40) with queue size 10 — see https://docs.harvestapi.io/guides/concurrency.md. Exceeding queue returns an error; the client surfaces 429 with Retry-After when present.

Validation errors (missing required identifier, requireAtLeastOne) are local HarvestValidationError before any request.

Raw API payloads are preserved in responses. Email fields are only marked verified if the API says so.

Development

npm ci
npm run lint        # eslint
npm run typecheck   # tsc --noEmit
npm run build       # tsc
npm test            # vitest
npm run test:coverage
npm run check       # lint + typecheck + build + test

Needs Node 20+.

Project Docs

• Endpoint inventory (30 endpoints): docs/harvestapi-endpoint-inventory.json

• Research notes & source URLs: docs/research-notes.md

• Tool mapping (Implemented / Intentionally Excluded): docs/tool-mapping.md

• Raw docs crawl: docs/raw/*.md

Security

• HARVESTAPI_KEY is only read from env (HARVESTAPI_KEY). Never logged, never included in error bodies beyond redacted hints.

• Never commit .env. .env.example contains placeholders only. .gitignore covers .env, node_modules, dist, coverage.

• Report security issues via GitHub Issues (do not post keys in issues).

Contributing

PRs welcome. Run npm run check before submitting. See docs/research-notes.md for how endpoints are sourced and validated.

License

MIT — see LICENSE.