# Needle MCP

Needle MCP server (v1).

The same outbound engine as the REST API, as tools your agent can call. Works with Claude Code, Cowork, Codex, Cursor, Hermes, or any MCP client.

Prefer HTTP? See the [API Reference](/docs/api-reference/introduction). New here? Start at the [onboarding skill](/agent-onboarding/SKILL.md).

## Set up Needle MCP

Every app signs you in with OAuth in your browser; no API key needed. An API key in the `Authorization` header works too, see [Authentication](/docs/authentication#mcp).

### Claude

Add Needle to Claude on the web and desktop with one click. No API key needed.

[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Needle&connectorUrl=https%3A%2F%2Fneedle.app%2Fmcp%2Fv1)

Claude opens its add dialog with Needle filled in. Click **Continue**, then **Connect**; sign in to Needle and click **Allow**.

### ChatGPT

Add Needle as a custom MCP app in ChatGPT. No API key needed.

1. In ChatGPT, open **Settings**, then **Security and login**, and turn on **Developer mode**.
2. Open [chatgpt.com/plugins](https://chatgpt.com/plugins) and click **+**.
3. Click **Create custom MCP server**, then **Create MCP App**.
4. Enter **Needle** as the **Name**. Under **Connection**, keep **Server URL** and paste `https://needle.app/mcp/v1`.
5. Keep **Authentication** on **OAuth**, tick **I understand and want to continue**, and click **Create**.

ChatGPT asks you to add Needle: click **Sign in with Needle**, sign in to Needle and click **Allow**.

### Codex

Run this in your terminal to add Needle as a remote MCP server in Codex. No API key needed.

```bash
codex mcp add needle --url https://needle.app/mcp/v1
```

Then run `codex mcp login needle`, sign in and click **Allow**. `codex mcp list` shows **needle** as enabled.

### Cursor

Add Needle to Cursor with one click. No API key needed.

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=needle&config=eyJ1cmwiOiJodHRwczovL25lZWRsZS5hcHAvbWNwL3YxIn0=)

Or paste this into `.cursor/mcp.json` or `~/.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "needle": {
      "url": "https://needle.app/mcp/v1"
    }
  }
}
```

Cursor opens Needle in your browser; sign in and click **Allow**.

### Grok

Add Needle as a custom connector on grok.com. No API key needed.

1. Open [grok.com/connectors](https://grok.com/connectors).
2. Click **New Connector**, then **Custom**.
3. Enter **Needle** as the name and `https://needle.app/mcp/v1` as the server URL.
4. Click **Add Connector**.

Grok opens Needle in your browser; sign in and click **Allow**.

### Grok Bot

Grok Bot adds connectors from chat; there is no settings form. No API key needed.

1. Open Grok Bot on desktop or iOS and start a chat.
2. Send this message:

```text
Add a custom MCP server called needle at https://needle.app/mcp/v1. It supports OAuth.
```

3. When Grok Bot asks to confirm, click **Add it**.
4. Click the connect card, sign in to Needle and click **Allow**.

Needle's tools are ready from your next message.

### OpenCode

Add this to `opencode.json`. No API key needed.

```json
{
  "mcp": {
    "needle": {
      "type": "remote",
      "url": "https://needle.app/mcp/v1",
      "enabled": true
    }
  }
}
```

Run `opencode mcp auth needle`, sign in and click **Allow**.

### Another app

Paste `https://needle.app/mcp/v1` where the app asks for an MCP server. On first use it opens a Needle sign-in page; sign in and click Allow.

## Features

- **Leads**: Build lead lists from LinkedIn and the Places API.
- **Campaigns**: Run multi-channel, multi-account outreach on LinkedIn and Instagram.
- **Drafts**: See drafted messages waiting for a person to review them before they send.
- **LinkedIn**: Search people and run outreach from connected accounts.
- **Instagram**: Reach people on Instagram from connected accounts.
- **Events**: Search activity across campaigns, leads, and connected accounts.
- **Places**: Find companies and locations to source lists.
- **Connected Accounts**: Connect LinkedIn and Instagram accounts to send from.
- **Suppressions**: Keep people and companies you should not contact off the list.
- **Webhooks**: Receive every outbound event at your own URL as it happens.
- **Compose**: Preview a message before you send it.
- **Files**: Store a private file (upload bytes, or copy a public URL), list files in the workspace, then attach one to a LinkedIn message or InMail.

## Authentication

Your MCP client signs you in. Claude.ai and Claude Desktop, Claude Code, Codex and ChatGPT developer mode open Needle in your browser on first use; sign in and click Allow. Tokens expire after an hour and refresh on their own. The session shows under [Settings → Sessions](/settings/sessions), where you can disconnect it. For Claude.ai and Claude Desktop, [add Needle as a custom connector](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Needle&connectorUrl=https%3A%2F%2Fneedle.app%2Fmcp%2Fv1) in one click. Each connection is bound to one user and one workspace. Listing tools at `/mcp/v1/tools` requires no sign-in.

## Tools

### Me

- [Get the authenticated user](/docs/mcp/needle-get-me)

### Connected accounts

- [List connected accounts](/docs/mcp/needle-list-connected-accounts)
- [Get a connected account](/docs/mcp/needle-get-connected-account)
- [Update a connected account](/docs/mcp/needle-update-connected-account)
- [Delete a connected account](/docs/mcp/needle-delete-connected-account)
- [List connected account limits](/docs/mcp/needle-list-connected-account-limits)
- [Override a connected account limit](/docs/mcp/needle-update-connected-account-limit)
- [Reset a connected account limit](/docs/mcp/needle-reset-connected-account-limit)
- [List connected account events](/docs/mcp/needle-list-connected-account-events)
- [List connected account tasks](/docs/mcp/needle-list-connected-account-tasks)

### Leads

- [List leads](/docs/mcp/needle-list-leads)
- [Create a lead](/docs/mcp/needle-create-lead)
- [Create or update a lead](/docs/mcp/needle-upsert-lead)
- [Create leads in bulk](/docs/mcp/needle-create-leads)
- [Get a lead](/docs/mcp/needle-get-lead)
- [Update a lead](/docs/mcp/needle-update-lead)
- [Update leads in bulk](/docs/mcp/needle-update-leads)
- [Delete a lead](/docs/mcp/needle-delete-lead)
- [Delete leads in bulk](/docs/mcp/needle-delete-leads)
- [List lead events](/docs/mcp/needle-list-lead-events)
- [List lead tasks](/docs/mcp/needle-list-lead-tasks)

### Campaigns

- [List campaigns](/docs/mcp/needle-list-campaigns)
- [Create a campaign](/docs/mcp/needle-create-campaign)
- [Get a campaign](/docs/mcp/needle-get-campaign)
- [Update a campaign](/docs/mcp/needle-update-campaign)
- [Archive a campaign](/docs/mcp/needle-archive-campaign)
- [Get campaign stats](/docs/mcp/needle-get-campaign-stats)
- [List campaign events](/docs/mcp/needle-list-campaign-events)
- [List campaign tasks](/docs/mcp/needle-list-campaign-tasks)
- [List campaign leads](/docs/mcp/needle-list-campaign-leads)
- [Enroll leads](/docs/mcp/needle-enroll-campaign-leads)
- [Stop a lead in a campaign](/docs/mcp/needle-remove-campaign-lead)
- [Stop leads in a campaign in bulk](/docs/mcp/needle-stop-campaign-leads)

### Drafts

- [List drafts](/docs/mcp/needle-list-drafts)

### Events

- [Search events](/docs/mcp/needle-search-events)

### LinkedIn

- [Get a LinkedIn profile](/docs/mcp/needle-get-linkedin-profile)
- [Search LinkedIn people](/docs/mcp/needle-search-linkedin-people)
- [Search LinkedIn people (Classic)](/docs/mcp/needle-search-linkedin-people-classic)
- [Search LinkedIn people (Sales Navigator)](/docs/mcp/needle-search-linkedin-people-sales-navigator)
- [Send a LinkedIn message](/docs/mcp/needle-send-linkedin-message)
- [Send a Sales Navigator InMail](/docs/mcp/needle-send-linkedin-in-mail)
- [Get remaining InMail credits](/docs/mcp/needle-get-linkedin-in-mail-balance)
- [List conversations](/docs/mcp/needle-list-linkedin-conversations)
- [List messages in a conversation](/docs/mcp/needle-list-linkedin-conversation-messages)
- [List pending invitations](/docs/mcp/needle-list-linkedin-invitations)
- [Send a connection invitation](/docs/mcp/needle-send-linkedin-invitation)
- [Withdraw an invitation](/docs/mcp/needle-withdraw-linkedin-invitation)
- [List invitations sent to you](/docs/mcp/needle-list-linkedin-received-invitations)
- [Accept or decline a received invitation](/docs/mcp/needle-respond-to-linkedin-invitation)
- [List followers](/docs/mcp/needle-list-linkedin-followers)
- [List accounts this account follows](/docs/mcp/needle-list-linkedin-following)
- [List first-degree connections](/docs/mcp/needle-list-linkedin-relations)
- [Get a LinkedIn company](/docs/mcp/needle-get-linkedin-company)
- [List jobs posted by a company](/docs/mcp/needle-list-linkedin-company-jobs)
- [List posts from a company page](/docs/mcp/needle-list-linkedin-company-posts)
- [Search LinkedIn jobs](/docs/mcp/needle-search-linkedin-jobs)
- [Get a LinkedIn job](/docs/mcp/needle-get-linkedin-job)
- [Search LinkedIn companies (Classic)](/docs/mcp/needle-search-linkedin-companies-classic)
- [Search LinkedIn posts](/docs/mcp/needle-search-linkedin-posts)
- [List posts by a person or company](/docs/mcp/needle-list-linkedin-posts)
- [Get a LinkedIn post](/docs/mcp/needle-get-linkedin-post)
- [List comments on a post](/docs/mcp/needle-list-linkedin-post-comments)
- [List reactions on a post](/docs/mcp/needle-list-linkedin-post-reactions)
- [Comment on a post](/docs/mcp/needle-comment-on-linkedin-post)
- [React to a post](/docs/mcp/needle-react-to-linkedin-post)
- [List LinkedIn search parameters](/docs/mcp/needle-list-linkedin-search-parameters)

### Instagram

- [Get an Instagram profile](/docs/mcp/needle-get-instagram-profile)
- [Get the connected account profile](/docs/mcp/needle-get-instagram-account-profile)
- [Send an Instagram message](/docs/mcp/needle-send-instagram-message)
- [React to an Instagram message](/docs/mcp/needle-react-to-instagram-message)
- [List Instagram conversations](/docs/mcp/needle-list-instagram-conversations)
- [List messages in a conversation](/docs/mcp/needle-list-instagram-conversation-messages)
- [List the participants of a conversation](/docs/mcp/needle-list-instagram-conversation-participants)
- [List the posts of an account](/docs/mcp/needle-list-instagram-posts)
- [Get an Instagram post](/docs/mcp/needle-get-instagram-post)
- [Publish an Instagram post](/docs/mcp/needle-create-instagram-post)
- [List the comments on a post](/docs/mcp/needle-list-instagram-post-comments)
- [Comment on a post](/docs/mcp/needle-comment-on-instagram-post)
- [List the likes on a post](/docs/mcp/needle-list-instagram-post-reactions)
- [Like a post](/docs/mcp/needle-like-instagram-post)
- [List followers](/docs/mcp/needle-list-instagram-followers)
- [List followed accounts](/docs/mcp/needle-list-instagram-following)
- [Follow an Instagram user](/docs/mcp/needle-follow-instagram-user)
- [Unfollow an Instagram user](/docs/mcp/needle-unfollow-instagram-user)

### Places

- [Search places](/docs/mcp/needle-search-places)
- [Get a place](/docs/mcp/needle-get-place)

### Compose

- [Preview an AI-composed message](/docs/mcp/needle-compose-preview)

### Files

- [List files](/docs/mcp/needle-list-files)
- [Create a file preview URL](/docs/mcp/needle-create-file-access-url)
- [Delete a file](/docs/mcp/needle-delete-file)
- [Create a file upload](/docs/mcp/needle-create-file-upload)

### Suppressions

- [List suppressions](/docs/mcp/needle-list-suppressions)
- [Create suppressions](/docs/mcp/needle-create-suppressions)
- [Check people and companies against the suppression list](/docs/mcp/needle-check-suppressions)
- [Delete a suppression](/docs/mcp/needle-delete-suppression)

### Webhooks

- [List webhooks](/docs/mcp/needle-list-webhooks)
- [Create a webhook](/docs/mcp/needle-create-webhook)
- [Get a webhook](/docs/mcp/needle-get-webhook)
- [Update a webhook](/docs/mcp/needle-update-webhook)
- [Delete a webhook](/docs/mcp/needle-delete-webhook)