Skip to content
Back to search

needle-mcp

Needle MCP Server for easy RAG.Long-term memory for LLMs.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/needle-ai--needle-mcp/badge.svg)](/listings/needle-ai--needle-mcp)

HTML

<a href="/listings/needle-ai--needle-mcp"><img src="/api/listings/needle-ai--needle-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Remote MCP Server (Recommended)

**Claude Desktop Config**

Create or update your config file: - For MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - For Windows: `%APPDATA%/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.needle.app/mcp",
        "--header",
        "Authorization:Bearer ${NEEDLE_API_KEY}"
      ],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

**Cursor Config**

Create or update `.cursor/mcp.json`:

{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.needle.app/mcp",
        "--header",
        "Authorization:${NEEDLE_AUTH_HEADER}"
      ],
      "env": {
        "NEEDLE_AUTH_HEADER": "Bearer <your-needle-api-key>"
      }
    }
  }
}

Get your API key from [Needle Settings](https://needle.app).

We provide two endpoints: - **Streamable HTTP**: `https://mcp.needle.app/mcp` (recommended) - **SSE**: `https://mcp.needle.app/sse`

Note: MCP deprecated SSE endpoints in the latest specification, so newer clients should prefer the Streamable HTTP endpoint.

2. Local Installation

1. Clone the repository:

git clone https://github.com/needle-ai/needle-mcp.git

2. Install UV globally using Homebrew:

brew install uv

3. Create your config file: - For MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - For Windows: `%APPDATA%/Claude/claude_desktop_config.json`

**Claude Desktop Config**

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

**Cursor Config**

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

4. Replace `/path/to/needle-mcp` with your actual repository path 5. Add your Needle API key 6. Restart Claude Desktop

**Installing via Smithery**

npx -y @smithery/cli install needle-mcp --client claude

3. Docker Installation

1. Clone and build:

git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .

2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

{
  "mcpServers": {
    "needle": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

3. Restart Claude Desktop

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 171 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Needle MCP
  2. ![Needle MCP](images/mcp-cover.webp)
  3. The [Needle](https://needle.app) outbound engine, as tools an agent can call. Build lead lists and run outreach on LinkedIn, Instagram, and email from Claude, ChatGPT, Codex, Cursor, Grok, OpenCode, or any MCP client.
  4. This repository is the setup guide. The server is hosted at:
  5. ```text
  6. https://needle.app/mcp/v1
  7. ```
  8. Parameters, limits, and the full tool list are in the [Needle MCP docs](https://needle.app/docs/mcp/introduction).
  9. ## What you can do
  10. - **Leads.** Build lead lists from LinkedIn and Places.
  11. - **Campaigns.** Run multi-channel, multi-account outreach on LinkedIn and Instagram.
  12. - **Drafts.** Draft messages for a person to review and approve before they send.
  13. - **LinkedIn.** Search people and run outreach from connected accounts.
  14. - **Instagram.** Reach people on Instagram from connected accounts.
  15. - **Events.** Search activity across campaigns, leads, and connected accounts.
  16. - **Places.** Find companies and locations to source lists.
  17. - **Connected accounts.** Connect LinkedIn and Instagram accounts to send from.
  18. - **Suppressions.** Keep people and companies you should not contact off the list.
  19. - **Webhooks.** Receive every outbound event at your own URL as it happens.
  20. - **Compose.** Preview a message before you send it.
  21. - **Files.** Store a private file, then attach it to a LinkedIn message or InMail.
  22. Prefer HTTP? Use the [API reference](https://needle.app/docs/api-reference/introduction). New to Needle? Start with the [onboarding skill](https://needle.app/agent-onboarding/SKILL.md).
  23. Install the Needle agent skill:
  24. ```bash
  25. npx skills add needle-ai/needle-mcp
  26. ```
  27. ## Example prompts
  28. Paste one of these into your agent once Needle is connected.
  29. ### Finish onboarding
  30. ```text
  31. Help me finish my Needle onboarding. Read my onboarding info to see my ideal customer profile, the leads Needle found, and my draft campaign. Then activate my campaign, and after that start looking for more leads.
  32. ```
  33. ### Leads from a LinkedIn post
  34. ```text
  35. Pull the people who commented on and reacted to this LinkedIn post: [paste the post URL]. Add the ones who fit my ideal customer as leads, skip anyone already in my workspace, and draft a short first message for the best fits.
  36. ```
  37. ### Warm intros
  38. ```text
  39. Look through my LinkedIn connections and find who can give me a warm intro to [name or company]. Rank the best paths, say why each person is a good route, and draft a short note I can send them.
  40. ```
  41. ## Set up
  42. Every app signs you in with OAuth in the browser. An API key in the `Authorization` header works too. See [Authentication](https://needle.app/docs/authentication#mcp).
  43. Listing tools at [`https://needle.app/mcp/v1/tools`](https://needle.app/mcp/v1/tools) does not require sign-in.
  44. ### Claude
  45. [Add Needle to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Needle&connectorUrl=https%3A%2F%2Fneedle.app%2Fmcp%2Fv1) on the web and desktop. Claude opens its add dialog with Needle filled in. Click **Continue**, then **Connect**. Sign in to Needle and click **Allow**.
  46. ### ChatGPT
  47. Add Needle as a custom MCP app. Developer mode has to be on.
  48. 1. In ChatGPT, open **Settings**, then **Security and login**, and turn on **Developer mode**.
  49. 2. Open [chatgpt.com/plugins](https://chatgpt.com/plugins) and click **+**.
  50. 3. Click **Create custom MCP server**, then **Create MCP App**.
  51. 4. Enter **Needle** as the name. Under **Connection**, keep **Server URL** and paste `https://needle.app/mcp/v1`.
  52. 5. Keep **Authentication** on **OAuth**, tick **I understand and want to continue**, and click **Create**.
  53. ChatGPT asks you to add Needle. Click **Sign in with Needle**, sign in, and click **Allow**.
  54. ### Codex
  55. ```bash
  56. codex mcp add needle --url https://needle.app/mcp/v1
  57. ```
  58. Then run `codex mcp login needle`, sign in, and click **Allow**. `codex mcp list` shows **needle** as enabled.
  59. ### Cursor
  60. [Add Needle to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=needle&config=eyJ1cmwiOiJodHRwczovL25lZWRsZS5hcHAvbWNwL3YxIn0=). Cursor opens Needle in the browser. Sign in and click **Allow**.
  61. Or paste this into `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (every project):
  62. ```json
  63. {
  64. "mcpServers": {
  65. "needle": {
  66. "url": "https://needle.app/mcp/v1"
  67. }
  68. }
  69. }
  70. ```
  71. ### Grok
  72. 1. Open [grok.com/connectors](https://grok.com/connectors).
  73. 2. Click **New Connector**, then **Custom**.
  74. 3. Enter **Needle** as the name and `https://needle.app/mcp/v1` as the server URL.
  75. 4. Click **Add Connector**.
  76. Grok opens Needle in the browser. Sign in and click **Allow**.
  77. ### Grok Bot
  78. Grok Bot adds connectors from chat.
  79. 1. Open Grok Bot on desktop or iOS and start a chat.
  80. 2. Send this message:
  81. ```text
  82. Add a custom MCP server called needle at https://needle.app/mcp/v1. It supports OAuth.
  83. ```
  84. 3. When Grok Bot asks to confirm, click **Add it**.
  85. 4. Click the connect card, sign in to Needle, and click **Allow**.
  86. Needle's tools are ready from the next message.
  87. ### OpenCode
  88. Add this to `opencode.json`:
  89. ```json
  90. {
  91. "mcp": {
  92. "needle": {
  93. "type": "remote",
  94. "url": "https://needle.app/mcp/v1",
  95. "enabled": true
  96. }
  97. }
  98. }
  99. ```
  100. Run `opencode mcp auth needle`, sign in, and click **Allow**.
  101. ### Another app
  102. 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**.
  103. ## Authentication
  104. Sign in, click **Allow**, and the connection is done. Each connection is bound to one user and one workspace. Tokens expire after an hour and refresh on their own. Sessions are listed under [Settings → Sessions](https://needle.app/settings/sessions), where you can disconnect one.
  105. To use an API key, send the same header as the REST API:
  106. ```text
  107. Authorization: Bearer sk-ndl-…
  108. ```
  109. Create a key under [API keys](https://needle.app/settings/api-keys). Each key is bound to one user and one workspace.
  110. ## Docs
  111. - [Needle MCP](https://needle.app/docs/mcp/introduction) — setup and every tool
  112. - [Authentication](https://needle.app/docs/authentication)
  113. - [API reference](https://needle.app/docs/api-reference/introduction)
  114. - [Onboarding skill](https://needle.app/agent-onboarding/SKILL.md)
  115. - [Agent docs index](https://needle.app/llms.txt)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.