Build Agents with Needle MCP Server

MCP (Model Context Protocol) server to manage documents and perform searches using Needle through Claude's Desktop Application.

Table of Contents

• Overview
• Features
• Usage
  • Commands in Claude Desktop
  • Result in Needle
• Installation
• Video Explanation

Overview

Needle MCP Server allows you to:

• Organize and store documents for quick retrieval.
• Perform powerful searches via Claude's large language model.
• Integrate seamlessly with the Needle ecosystem for advanced document management.

MCP (Model Context Protocol) standardizes the way LLMs connect to external data sources. You can use Needle MCP Server to easily enable semantic search tools in your AI applications, making data buried in PDFs, DOCX, XLSX, and other files instantly accessible by LLMs.

We recommend using our remote MCP server for the best experience - no local setup required.

Features

• Document Management: Easily add and organize documents on the server.
• Search & Retrieval: Claude-based natural language search for quick answers.
• Easy Integration: Works with Claude Desktop and Needle collections.

Usage

Commands in Claude Desktop

Below is an example of how the commands can be used in Claude Desktop to interact with the server:

1. Open Claude Desktop and connect to the Needle MCP Server.
2. Use simple text commands to search, retrieve, or modify documents.
3. Review search results returned by Claude in a user-friendly interface.

Result in Needle

https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c

Youtube Video Explanation

For a full walkthrough on using the Needle MCP Server with Claude and Claude Desktop, watch this YouTube explanation video.

Installation

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.

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

... View full README on GitHub