How do I use Grinfi MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Grinfi MCP Server Show me all my contacts" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Grinfi MCP Server

by alex-rise

Overview Schema Related Servers Score Discussions

JavaScript

Hybrid

Grinfi MCP Server

Connect Claude to your Grinfi.io account. Manage contacts, automations, messages, and more — all through natural language.

Quick Start

1. Get your API key

Go to Grinfi → Settings → API Keys and copy your key.

2. Download this repository

Click the green "Code" button above → "Download ZIP", then unzip it.

Or clone with Git:

git clone https://github.com/alex-rise/grinfi-mcp-server.git

3. Run the installer for your OS

Related MCP server: mcp-server-systemeio

macOS Installation

Option A: Use the installer (recommended)

Open the grinfi-mcp-server folder in Finder
Double-click install.sh
When prompted, paste your Grinfi API key and press Enter

The installer will automatically:

Install Homebrew (if not installed)
Install Node.js (if not installed)
Install all dependencies and build the server
Configure Claude Desktop

Note: If macOS asks for your password, enter your Mac login password and press Enter. This is normal — it's installing system packages.

Option B: Manual setup (macOS)

cd grinfi-mcp-server
npm install
npm run build

Then add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "grinfi": {
      "command": "node",
      "args": ["/full/path/to/grinfi-mcp-server/dist/index.js"],
      "env": {
        "GRINFI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows Installation

Option A: Use the installer (recommended)

Open the grinfi-mcp-server folder in File Explorer
Double-click install.bat
If Windows shows a security warning ("Windows protected your PC"), click "More info" then "Run anyway"
When prompted, paste your Grinfi API key and press Enter

The installer will automatically:

Install Node.js via winget (if not installed)
Install all dependencies and build the server
Configure Claude Desktop

Option B: Manual setup (Windows)

cd grinfi-mcp-server
npm install
npm run build

Then add this to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "grinfi": {
      "command": "node",
      "args": ["C:/full/path/to/grinfi-mcp-server/dist/index.js"],
      "env": {
        "GRINFI_API_KEY": "your-api-key-here"
      }
    }
  }
}

After Installation (All Platforms)

Restart Claude Desktop — quit completely (not just close the window) and reopen
Look for "grinfi" in the tools list (hammer icon at the bottom of the chat)
Start chatting! Try: "Show me all my contacts"

Claude Code Configuration

claude mcp add grinfi -- node /full/path/to/grinfi-mcp-server/dist/index.js

Then set the environment variable before running Claude Code:

export GRINFI_API_KEY="your-api-key-here"
claude

Cloud Endpoint (Paid Claude plans)

If you have a paid Claude plan, you can use our hosted cloud endpoint — no local installation needed.

Visit mcp.grinfi.io to generate your personal MCP endpoint URL.

Available Tools

Contacts

Tool	Description
`find_contact`	Find a contact by LinkedIn ID, email, or name + company
`search_contacts`	Search contacts with filters, sorting, pagination
`get_contact`	Get contact details by UUID
`update_contact`	Update contact fields
`delete_contact`	Delete a contact
`upsert_contact`	Create or update a contact in a list

Lists

Tool	Description
`list_lists`	Get all contact lists
`get_list`	Get a list by UUID
`create_list`	Create a new list

Automations

Tool	Description
`list_automations`	Get all automations
`start_automation`	Start an automation
`stop_automation`	Stop an automation
`add_contact_to_automation`	Add existing contact to automation
`add_new_contact_to_automation`	Create contact and add to automation
`cancel_contact_from_automations`	Cancel contact from specific automations
`cancel_contact_from_all_automations`	Cancel contact from all automations

Unibox (Messages)

Tool	Description
`list_linkedin_messages`	List LinkedIn messages
`get_unread_conversations`	Get contacts with unread messages
`mark_conversation_as_read`	Mark a LinkedIn conversation as read
`send_linkedin_message`	Send a LinkedIn message
`list_emails`	List emails
`send_email`	Send an email

Sender Profiles

Tool	Description
`list_sender_profiles`	List all sender profiles
`get_sender_profile`	Get sender profile details
`create_sender_profile`	Create a new sender profile

CSV Import / Export (new in 1.1)

Tool	Description
`upload_csv`	Upload a CSV file from local disk; returns a file_import UUID
`import_leads_from_file`	Import contacts from an uploaded CSV with column mapping
`import_companies_from_file`	Import companies from an uploaded CSV
`export_leads_csv`	Queue a CSV export of contacts matching a filter
`export_companies_csv`	Queue a CSV export of companies matching a filter
`download_export`	Get the download payload for a queued export

Lead Enrichment & Analytics (new in 1.1)

Tool	Description
`enrich_leads`	Trigger advanced LinkedIn enrichment for contacts
`count_leads`	Count contacts matching a filter
`get_leads_metrics`	Get team engagement metrics for contacts

Automation Folders & Enrollment

Tool	Description
`list_automation_folders`	List automation folders (renamed from `list_flow_workspaces` in 1.2)
`create_automation_folder`	Create a new automation folder (renamed in 1.2)
`update_automation_folder`	Rename or change display order (renamed in 1.2)
`delete_automation_folder`	Delete a folder (automations inside are not deleted) (renamed in 1.2)
`list_flow_leads`	Search contacts enrolled in automations
`delete_flow_lead_history`	Delete a contact's automation history (full erase)

AI Agents & Templates — full CRUD (new in 1.1)

Tool	Description
`create_ai_agent`	Create a new AI agent
`update_ai_agent`	Update an AI agent
`delete_ai_agent`	Delete an AI agent
`update_ai_template`	Update an AI template
`delete_ai_template`	Delete an AI template

Closures (new in 1.1)

Tool	Description
`upload_attachment`	Upload a local file as an attachment
`remove_from_leads_blacklist`	Remove a contact from the leads blacklist
`remove_from_companies_blacklist`	Remove a company from the companies blacklist
`update_custom_field`	Rename a custom field or change order
`delete_custom_field`	Delete a custom field (and all its values)

Failed-task triage (new in 1.2)

Tool	Description
`diagnose_failed_tasks`	Read-only triage: failure breakdown by error code, per-sender, sample tasks, pattern hints (captcha/proxy/rate-limit detection)
`restart_failed_tasks`	Bulk-retry failed automation tasks (filter or explicit UUIDs); supports `dry_run`
`skip_failed_tasks`	Bulk-skip failed tasks (lead progresses to next node)
`restart_failed_tasks_from_top`	Re-enrol matched leads from the start of a flow; optionally swap to a different sender

Workspace dashboard & health (new in 1.2)

Tool	Description
`workspace_health_check`	Single-call 6-section operational overview: today/yesterday counts, LinkedIn fleet, mailbox health, active flows, failed tasks
`get_dashboard`	CRM analytics widgets: activities-over-time, conversion-funnel, pipeline-distribution, sender-performance, response-rate
`send_volume_report`	Period-aware outreach event counts with flexible group_by (type, status, flow, sender, day, week)
`diagnose_mailbox`	Deep mailbox health diagnosis with detected issues + recommendations
`get_health_snapshots`	Fleet-wide LinkedIn account snapshot (status, cookie, health score, daily caps)

LinkedIn browsers (new in 1.2)

Tool	Description
`list_linkedin_browsers`	List all LinkedIn browser profiles
`get_linkedin_browser`	Get a browser by ID
`create_linkedin_browser`	Create a browser linked to a sender profile
`delete_linkedin_browser`	Delete a browser (irreversible)
`run_linkedin_browser` / `stop_linkedin_browser`	Start / stop a browser session
`set_linkedin_browser_proxy`	Change proxy country
`share_linkedin_browser`	Share browser access with team members by email
`diagnose_linkedin_browser`	Deep health diagnosis on one browser (cookie, health score, limits, proxy)

Data sources (LinkedIn import jobs) (new in 1.2)

Tool	Description
`list_data_sources` / `get_data_source`	Discover & inspect import jobs
`create_data_source`	Create import from CSV / Sales Navigator / LinkedIn search / post engagement
`update_data_source` / `delete_data_source`	Edit or remove an import job

Account & teams (new in 1.2)

Tool	Description
`get_current_user`	Authenticated user profile
`list_teams`	All teams accessible via the Grinfi API (vs `list_my_teams` for locally-configured keys)
`get_team`	Team details by numeric ID

Integrations & diagnostics (new in 1.2)

Tool	Description
`call_external_api`	Ad-hoc outbound HTTP request (SSRF-protected, public URLs only, 1MB cap)
`list_outbound_log`	Outbound HTTP log: webhook deliveries, automation API calls, enrichment requests
`test_llm_connection`	Smoke-test a stored LLM integration (~5 token cost)

CRM read & helpers (new in 1.3)

Tool	Description
`get_leads_by_uuids`	Fetch multiple contacts by their UUIDs in one round-trip
`list_lead_uuids`	Lightweight UUID-only listing of leads matching a filter (much smaller than `search_contacts`)
`list_company_uuids`	Lightweight UUID-only listing of companies matching a filter
`suggest_lead_filter_values`	Typeahead suggestions for contact filter fields — discover valid values to filter by
`suggest_company_filter_values`	Typeahead suggestions for company filter fields
`create_lead`	Create one or more leads in a target list (bulk-friendly alternative to `upsert_contact`)

Metrics & statistics (new in 1.3)

Tool	Description
`get_custom_field_metrics`	Usage metrics for custom fields — how many records have a value set
`get_pipeline_stage_metrics`	Funnel analytics: how many leads/companies sit in each pipeline stage
`get_sender_profile_metrics`	Per-sender analytics: sends, replies, bounces, response-rate
`get_outreach_metrics`	High-level outreach analytics in one call: connection requests sent vs accepted, messages, replies
`get_ai_agent_lead_metrics`	Performance metrics for AI agents — leads engaged by engagement status
`get_flow_node_statistics`	Per-step funnel for an automation: how many leads passed each node and where they dropped off
`get_flow_contact_source_statistics`	Per-contact-source breakdown of leads inside an automation
`get_enrichment_queue_metrics_filtered`	Enrichment-queue metrics for the current month, optionally narrowed by a filter
`get_enrichment_queue_item`	Fetch a single enrichment-queue item by numeric ID (provider, status, cost, target)

Mass actions (new in 1.3)

Tool	Description
`leads_mass_action_by_filter`	Default filter-based bulk contact op — server fetches UUIDs, chunks them, applies the action (supports `dry_run`)
`list_mass_actions`	Browse the history of mass-action jobs run on this workspace
`get_mass_action_status`	Poll the status of a specific mass-action job by UUID
`get_mass_action_metrics`	Execution metrics for mass-action jobs — progress, succeeded/failed counts
`cancel_mass_action`	Abort a still-running mass-action job before it finishes

CSV bulk update (new in 1.3)

Tool	Description
`update_leads_from_csv`	Bulk-update existing contacts from a local CSV (matched by uuid/email)
`update_companies_from_csv`	Bulk-update existing companies from a local CSV
`add_to_blacklist_from_csv`	Bulk-add contacts to the blacklist from a local CSV (emails, LinkedIn IDs, or UUIDs)

These take a local file_path (like upload_csv) — the server reads the file from disk.

Lead imports — LinkedIn / Sales Navigator (new in 1.3)

Tool	Description
`import_ln_leads_search`	Queue a regular LinkedIn (non-Sales-Navigator) people-search import
`import_ln_my_network`	Queue an import of your own LinkedIn 1st-degree connections
`import_post_engagement`	Harvest people who liked, reposted, or commented on a specific LinkedIn post
`import_sn_accounts_search`	Queue a Sales Navigator company search import
`import_sn_dynamic_search`	Queue an import from a Sales Navigator ad-hoc (non-saved) search URL
`import_sn_saved_search`	Queue an import from a Sales Navigator saved search URL

Tasks (new in 1.3)

Tool	Description
`list_tasks_simple`	Simple GET-based automation-tasks listing with query-string pagination
`count_tasks`	Count automation tasks matching a filter without fetching the rows
`get_task_metrics`	Task-execution metrics aggregated by sender profile and status
`update_task`	Update editable fields of an automation task (reschedule, reassign, edit payload)

Flows / automations (new in 1.3)

Tool	Description
`create_flow`	Create a brand-new automation from scratch with custom nodes (steps)
`publish_flow_publicly`	Make a flow accessible via a public share link
`get_public_flow`	Fetch the public/shared definition of a flow by its share UUID (read-only)
`get_all_sender_profiles_for_flows`	Return every sender profile referenced by a list of flow UUIDs, in one call

Mailboxes & sender profiles (new in 1.3)

Tool	Description
`activate_mailboxes_bulk`	Enable sending on a set of mailboxes in one call
`deactivate_mailboxes_bulk`	Pause sending on a set of mailboxes in one call
`reconnect_mailbox_smtp`	Re-establish a mailbox's SMTP connection with fresh credentials
`setup_mailbox_tracking_domain`	Attach a custom (branded) open/click tracking domain to a mailbox
`remove_mailbox_tracking_domain`	Revert a mailbox's tracking to the default platform domain
`detect_email_provider`	Detect the email provider (Gmail, Outlook, Yandex, custom SMTP) for an address via MX lookup
`check_sender_status`	One-call dispatch-readiness check for a sender across LinkedIn + email channels
`disable_smart_limits_for_sender`	Turn off smart-limits enforcement on a sender profile
`enable_smart_limits_for_sender`	Turn on smart-limits enforcement (throttle near daily safety limits)
`list_sender_profiles_filtered`	Browse sender profiles with filtering, sorting, and pagination

LinkedIn browsers — external cloud (new in 1.3)

Tool	Description
`update_linkedin_browser`	Update a LinkedIn browser profile by internal ID (name, proxy, sharing)
`check_linkedin_browser_proxy`	Test a proxy configuration before assigning it to a browser
`connect_linkedin_browser_to_external_cloud`	Connect a browser profile to an external cloud runner via a shared access key
`generate_external_browser_access_key`	Mint an external-cloud access key for a LinkedIn browser profile
`run_linkedin_browser_external`	Start a browser session in an externally-hosted environment via a pre-shared access key

Export webhooks (new in 1.3)

Tool	Description
`trigger_lead_export_webhook`	Manually fire the "lead exported" webhook for a set of leads (replay a delivery)
`trigger_company_export_webhook`	Manually fire the "company exported" webhook for a set of companies

Example Conversations

Find a contact:

"Find the contact with email john@example.com"

Search with filters:

"Show me contacts at Google created after January 2024"

Manage automations:

"List my automations and start the one called CMO Germany"

Send messages:

"Send a LinkedIn message to Anna saying we have a new case study"

Troubleshooting

"GRINFI_API_KEY is not set"

Make sure your API key is configured. Re-run the installer or edit the Claude Desktop config file manually (see Manual Setup sections above).

Tools not showing in Claude

Make sure Claude Desktop is fully restarted (quit and reopen, not just close window)
Check the config file path is correct for your OS
Make sure the path to dist/index.js is absolute (starts with / on Mac or C:\ on Windows)

API errors (401/403)

Your API key may be invalid or expired. Generate a new one in Grinfi → Settings → API Keys.

Build errors

cd grinfi-mcp-server
rm -rf node_modules dist
npm install
npm run build

Installer won't start (Mac)

If double-click doesn't work, open Terminal and run:

bash /Users/yourname/Documents/grinfi-mcp-server/install.sh

Installer won't start (Windows)

Make sure you're double-clicking install.bat (not install.ps1). If Windows blocks it, click "More info" → "Run anyway".

If that doesn't work, open PowerShell manually (press Win + X, choose "PowerShell"), then run:

cd "$HOME\Documents\grinfi-mcp-server"
powershell -ExecutionPolicy Bypass -File install.ps1

Requirements

Node.js 18+ — installed automatically by the installer, or download manually
Claude Desktop — download here
Grinfi.io account with an API key

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

1wRelease cycle

2Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/alex-rise/grinfi-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server