Skip to main content
Glama
Needle MCP Server

Needle MCP Server

Official
by needle-ai

Needle MCP

Needle MCP

The Needle 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.

This repository is the setup guide. The server is hosted at:

https://needle.app/mcp/v1

Parameters, limits, and the full tool list are in the Needle MCP docs.

What you can do

  • Leads. Build lead lists from LinkedIn and Places.

  • Campaigns. Run multi-channel, multi-account outreach on LinkedIn and Instagram.

  • Drafts. Draft messages for a person to review and approve 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, then attach it to a LinkedIn message or InMail.

Prefer HTTP? Use the API reference. New to Needle? Start with the onboarding skill.

Install the Needle agent skill:

npx skills add needle-ai/needle-mcp

Related MCP server: Documentation MCP Server

Example prompts

Paste one of these into your agent once Needle is connected.

Finish onboarding

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.

Leads from a LinkedIn post

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.

Warm intros

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.

Set up

Every app signs you in with OAuth in the browser. An API key in the Authorization header works too. See Authentication.

Listing tools at https://needle.app/mcp/v1/tools does not require sign-in.

Claude

Add Needle to Claude 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.

ChatGPT

Add Needle as a custom MCP app. Developer mode has to be on.

  1. In ChatGPT, open Settings, then Security and login, and turn on Developer mode.

  2. Open 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, and click Allow.

Codex

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. Cursor opens Needle in the browser. Sign in and click Allow.

Or paste this into .cursor/mcp.json (this project) or ~/.cursor/mcp.json (every project):

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

Grok

  1. Open 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 the browser. Sign in and click Allow.

Grok Bot

Grok Bot adds connectors from chat.

  1. Open Grok Bot on desktop or iOS and start a chat.

  2. Send this message:

Add a custom MCP server called needle at https://needle.app/mcp/v1. It supports OAuth.
  1. When Grok Bot asks to confirm, click Add it.

  2. Click the connect card, sign in to Needle, and click Allow.

Needle's tools are ready from the next message.

OpenCode

Add this to opencode.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.

Authentication

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, where you can disconnect one.

To use an API key, send the same header as the REST API:

Authorization: Bearer sk-ndl-…

Create a key under API keys. Each key is bound to one user and one workspace.

Docs

Available Tools

7 tools
needle_add_fileAInspect

Add a new document to a Needle collection by providing a URL for download. Supports multiple file formats including: - PDF documents - Microsoft Word files (DOC, DOCX) - Plain text files (TXT) - Web pages (HTML)

        The document will be:
        1. Downloaded from the provided URL
        2. Processed for text extraction
        3. Indexed for semantic search
        
        Use this tool when you need to:
        - Add new documents to a collection
        - Make documents searchable
        - Expand your knowledge base
        
        Important: Documents require processing time before they're searchable.
        Check processing status using needle_list_files before searching new content.

Inputs: collection_id (required), name (required), url (required).

needle_create_collectionAInspect

Create a new document collection in Needle for organizing and searching documents. A collection acts as a container for related documents and enables semantic search across its contents. Use this tool when you need to: - Start a new document organization - Group related documents together - Set up a searchable document repository Returns a collection ID that's required for subsequent operations. Choose a descriptive name that reflects the collection's purpose for better organization.

Inputs: name (required).

needle_get_collection_detailsAInspect

Fetch comprehensive metadata about a specific Needle collection. Provides detailed information about the collection's configuration, creation date, and current status. Use this tool when you need to: - Verify a collection's existence and configuration - Check collection metadata before operations - Get creation date and other attributes Requires a valid collection ID and returns detailed collection metadata. Will error if collection doesn't exist.

Inputs: collection_id (required).

needle_get_collection_statsAInspect

Retrieve detailed statistical information about a Needle collection's contents and status. Provides metrics including: - Total number of documents - Processing status of documents - Storage usage and limits - Index status and health Use this tool to: - Monitor collection size and growth - Verify processing completion - Check collection health before operations Essential for ensuring collection readiness before performing searches.

Inputs: collection_id (required).

needle_list_collectionsAInspect

List Needle collections. Returns maximum of 20 results. Get more results by increasing the offset. Returns detailed information including collection IDs, names, and creation dates. Use this tool when you need to: - Get an overview of available document collections - Find collection IDs for subsequent operations - Verify collection existence before performing operations The response includes metadata that's required for other Needle operations.

Inputs: offset.

needle_list_filesAInspect

List all documents stored within a specific Needle collection with their current status. Returns detailed information about each file including: - File ID and name - Processing status (pending, processing, complete, error) - Upload date and metadata Use this tool when you need to: - Inventory available documents - Check processing status of uploads - Get file IDs for reference - Verify document availability before searching Essential for monitoring document processing completion before performing searches.

Inputs: collection_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: collection management (create, list, get details, get stats), file management (add, list), and search. The descriptions explicitly differentiate their functions, such as needle_get_collection_details for metadata vs. needle_get_collection_stats for metrics, eliminating any ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with the 'needle_' prefix, using snake_case throughout (e.g., needle_create_collection, needle_list_files). This predictable naming scheme makes it easy for agents to understand and select tools based on their actions and targets.

    Tool Count5/5

    With 7 tools, the server is well-scoped for document management and search, covering essential operations like collection CRUD, file addition, status monitoring, and semantic search. Each tool serves a clear purpose without redundancy, fitting the domain's needs efficiently.

    Completeness4/5

    The toolset provides strong coverage for core document management workflows, including collection lifecycle, file processing, and search. A minor gap exists in file deletion or update capabilities, which could limit full CRUD operations, but agents can still perform key tasks like adding, listing, and searching documents effectively.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers