open-email-harvester
Enables LangChain applications to call the local REST/OpenAPI bridge to query and manage contacts, run extraction from text or HTML, validate emails, and export contact data.
Lets n8n workflows use the local REST/OpenAPI bridge to manage harvested contacts, extract contacts from supplied content, validate emails, and export or query domains.
Allows local LLMs served through Ollama to call the REST/OpenAPI bridge for contact management, extraction, validation, and export.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Open Email Harvester
Privacy-first contact extractor for any website, any browser, and any AI.
Scan a page to pull out emails (obfuscated ones too), phone numbers, social/profile links, names, the page title, the source URL and the company domain. Your contacts stay in your browser. If you want an AI assistant to work with them, connect it through MCP or a localhost REST/OpenAPI bridge.
CI workflow:
ci/github-actions-ci.yml. Copy it to.github/workflows/ci.ymlto enable GitHub Actions (lint + tests on Node 18/20/22 + web-ext lint).
Why it's different
🔒 Privacy-first, local-only | Contacts live in |
🌐 Works on any site | Nothing is tied to a particular website. It uses |
🧭 Works in any browser | One Manifest V3 build runs in Chrome, Edge, Brave, Opera, Vivaldi and Firefox (128+). A small |
🤖 Works with any AI | A built-in MCP server covers Claude Desktop, Cursor, ChatGPT connectors and other MCP clients. A REST bridge with an OpenAPI spec covers everything else: custom GPT actions, LangChain, n8n, scripts. |
🕵️ Catches obfuscated emails | It finds |
Related MCP server: MCP Google Contacts Server
Features
Scan the current page with a click or Alt+Shift+E, or turn on auto-scan.
Extracts emails, phones, social links (GitHub, X/Twitter, Facebook, Instagram, YouTube, Mastodon, Bluesky and more), guessed names, page title, source URL and domain/company.
Validity hints that work offline: each email is checked for syntax, matched against a disposable-domain list and flagged if it's a role account (
info@,support@and so on). These checks make no network calls.Manage your list: duplicates are merged automatically. You can add tags and notes, search everything (or type
#tagto filter by tag), filter by type and group by domain.Export/import as CSV or JSON, or clear everything.
Optional sync to the local bridge. It's off by default and only accepts localhost URLs.
Repository layout
extension/ MV3 extension (popup, options, background, content, src/ shared logic)
server/ mcp.js (MCP stdio server), bridge.js (REST), host.js (lifecycle), openapi.yaml, db.js
scripts/ Windows auto-start installer and packaging helpers
skills/ AI skills for the full extension and the outreach CRM
test/ node:test unit testsInstall the extension
First, download open-email-harvester-extension-v1.0.0.zip from Releases and unzip it, or clone this repo and use the extension/ folder.
Chrome / Brave / Opera / Vivaldi
Open
chrome://extensions(brave://extensions,opera://extensions).Turn on Developer mode.
Click Load unpacked and select the
extension/folder.
Microsoft Edge
Open
edge://extensions.Turn on Developer mode.
Click Load unpacked and select
extension/.
Firefox (128+)
To try it temporarily: open
about:debugging#/runtime/this-firefox, click Load Temporary Add-on… and pickextension/manifest.json.To install it permanently: sign it with
npx web-ext sign --source-dir extensionusing your own AMO credentials, or install it in Developer Edition/Nightly withxpinstall.signatures.required=false.
Using it
Open any page and click the toolbar icon, then Scan this page.
To scan pages as they load, open Settings, turn on Auto-scan and accept the optional permission.
Start the local services automatically (Windows)
The extension cannot launch an arbitrary Node process by itself. Run this one-time setup from the cloned repository instead:
npm run autostart:installThis registers a per-user Windows Scheduled Task that starts the localhost bridge at sign-in. When Chrome starts, the extension waits for the bridge and opens the dashboard. The Open the local dashboard when Chrome starts setting can turn that tab off without stopping the service. Remove the task with:
npm run autostart:uninstallThe MCP entrypoint is independent of Chrome: when an AI client launches server/mcp.js, it checks the health endpoint and starts the same local bridge on demand if needed. Set OEH_AUTO_START_BRIDGE=0 to disable that behavior. The bridge remains bound to localhost and inherits only the environment variables already configured for that user.
Connect an AI
You'll need Node 18 or newer. Clone the repo; the server has no runtime dependencies:
git clone https://github.com/tanmayrastogi57/open-email-harvester && cd open-email-harvesterBy default, data is stored in ~/.open-email-harvester/contacts.json. To change that, set OEH_DATA.
MCP tools
Tool | What it does |
| List contacts. Filter by |
| Full-text search |
| Add contacts (duplicates are merged) |
| Add tags or notes to a contact |
| Delete a contact |
| Run the extractor on text or HTML the AI provides, optionally saving the results |
| Offline validity hint |
| Number of contacts per domain |
| Export as CSV or JSON |
Claude Desktop
Edit claude_desktop_config.json. It's in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows:
{ "mcpServers": { "open-email-harvester": { "command": "node", "args": ["/ABS/PATH/open-email-harvester/server/mcp.js"] } } }Restart Claude Desktop.
Cursor
Add the same block to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.
VS Code (Copilot), Windsurf, Cline, Continue, Zed and other MCP clients
Use stdio transport with the command node /ABS/PATH/server/mcp.js.
ChatGPT, custom GPTs, Gemini, local LLMs and other non-MCP tools
Start the bridge if you are using REST directly and have not installed the Windows auto-start task:
node server/bridge.js # http://127.0.0.1:8765 OEH_TOKEN=choose-a-secret node server/bridge.js # optional bearer tokenPoint your tool at the spec:
http://127.0.0.1:8765/openapi.yaml(the same file is atserver/openapi.yaml).Custom GPT actions: these need a public HTTPS URL. If you want that, expose the bridge yourself through a tunnel and set
OEH_TOKEN.Ollama, LM Studio, LangChain, n8n and scripts: call the REST endpoints directly.
Syncing the extension to the bridge
Open extension Settings, turn on Sync, keep the URL as http://127.0.0.1:8765 and enter the token if you set one. New scans are then sent to the bridge, so your AI sees them. The Sync button in the popup pushes everything you've already saved.
Outreach CRM
The local bridge also includes a privacy-first outreach tracker. It stores data at ~/.open-email-harvester/outreach.json unless OEH_OUTREACH_DATA is set.
Start the bridge and open http://127.0.0.1:8765/outreach/dashboard to view harvested contacts, sent contacts, replies, follow-up status, and job metadata. The harvested-contact table is populated when extension Sync is enabled; otherwise scans remain in browser storage. The MCP server exposes list_outreach, upsert_outreach, record_outreach_event, set_outreach_followup, outreach_summary, and export_outreach.
The tracker does not send mail or scrape private addresses. Gmail synchronization can be AI-triggered through an AI client's Gmail connector, or can run directly through the bridge after the user completes local Gmail OAuth. Both paths search sent mail and replies, then write metadata using Gmail messageId and threadId. Sending a message manually in Gmail is reflected after the next sync.
The local tracker stores outreach metadata and event history, not Gmail credentials or full message bodies. The dashboard binds to 127.0.0.1 and is visible only on the machine running the bridge unless you deliberately deploy and secure it. Each person who installs the project must connect their own AI client and Gmail account; the repository contains no user outreach data.
Direct Gmail connection
The bridge can sync Gmail without an AI in the loop. Create a Google OAuth 2.0 client for a local/web application, enable the Gmail API, and register the exact redirect URI http://127.0.0.1:8765/auth/gmail/callback. See Google's OAuth web-server flow and Gmail message-list documentation. Start the bridge with:
OEH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
OEH_GOOGLE_CLIENT_SECRET=your-client-secret \
node server/bridge.jsOn Windows PowerShell:
$env:OEH_GOOGLE_CLIENT_ID = 'your-client-id.apps.googleusercontent.com'
$env:OEH_GOOGLE_CLIENT_SECRET = 'your-client-secret'
node server/bridge.jsThen click Connect Gmail in the dashboard or extension settings. The bridge requests read-only Gmail access, reads message metadata with format=metadata, stores the refresh token in ~/.open-email-harvester/gmail-tokens.json, and syncs periodically. Set OEH_GMAIL_SYNC_INTERVAL_MS=0 to disable background sync. The token file is local and ignored by Git; protect the machine. Disconnect removes the local token; revoke the app separately from the Google Account security page if needed.
The bridge and AI use the same reconciliation function. Direct Gmail sync and the MCP tool reconcile_outreach_from_gmail both deduplicate by Gmail message/thread IDs and can correct stale recipient, subject, role, and status metadata without storing message bodies.
AI skill
The repository includes skills/open-email-harvester/SKILL.md for the full extension workflow and skills/open-email-harvester-outreach/SKILL.md for the narrower outreach CRM workflow. Install or link the relevant skill into the AI client’s skill directory. MCP tool descriptions remain the source of truth for available operations; the skills tell the AI to check connection status, sync before answering current outreach questions, preserve Gmail IDs, and avoid storing bodies or credentials.
REST quick reference
GET /health
GET /contacts?query=&tag=&type=email|phone|social&domain=
POST /contacts body: contact or [contacts]
PATCH /contacts/{id} body: {tags:[], notes:""}
DELETE /contacts/{id} | DELETE /contacts
GET /domains
GET /export?format=csv|json
POST /extract body: {text, html, url, title, links[], save}
GET /validate?email=Example:
curl -s -X POST localhost:8765/extract -H 'content-type: application/json' \
-d '{"text":"jane [at] example [dot] com, +1 555 010 0199","save":true}'Development
npm ci
npm test # unit tests (node:test)
npm run lint # eslint
npm run lint:ext # web-ext lint
npm run package # builds dist/*.zipResponsible use
Only collect contact data you're allowed to process, and follow privacy and anti-spam laws (GDPR, CAN-SPAM, etc.) and each site's terms. The tool doesn't get around logins or paywalls. It only reads pages you have open.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A private address book your AI can search, update and import into.
Verify and find B2B emails, search leads and run bulk jobs from your AI assistant.
Search B2B people, companies and local businesses and build lead lists from your AI assistant.
An AI-first personal CRM you run in natural language: contacts, reminders, notes, and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceConnects AI assistants to macOS Contacts app, allowing users to search, view, add, and update contacts through natural language conversations.511MIT
- AlicenseNot gradedqualityDmaintenanceGives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage contacts with full CRUD, dedup, merge, import/export, sync with Google/Apple/CardDAV, and git-backed rollback.5 npmAGPL 3.0
- AlicenseNot gradedqualityDmaintenanceAllows AI assistants to preview, confirm, import, search, and manage NFC/QR digital business cards through a private Cloudflare-deployed contact library.Apache 2.0