Needle MCP

What is Needle MCP about?

Needle MCP enables LLMs to store, organize, and retrieve documents quickly, turning static files such as PDFs, DOCX, and XLSX into searchable knowledge that can be accessed through natural language queries.

How to use Needle MCP?

• Remote (recommended): Add a server entry to Claude Desktop or Cursor config that runs npx mcp-remote https://mcp.needle.app/mcp --header "Authorization:Bearer ${NEEDLE_API_KEY}". Supply your Needle API key in the environment.
• Local source: Clone the repo, install the uv tool, and run the server with uv --directory /path/to/needle-mcp run needle-mcp (or via Docker using the provided Dockerfile).
• Docker: Build the image (docker build -t needle-mcp .) and invoke it with docker run --rm -i needle-mcp from the client configuration.
• After configuration, use simple text commands in Claude Desktop (e.g., "Create a new collection called 'Technical Docs'" or "Search the collection for information about AI") to interact with the server.

Key Features of Needle MCP

• Document Management: add, organize, and list collections.
• Claude‑based natural language search for instant answers.
• Seamless integration with Needle collections and Claude Desktop.
• Supports remote, local, and Docker deployments.
• Works with any client that implements the Model Context Protocol.

Use Cases of Needle MCP

• Enhance Retrieval‑Augmented Generation pipelines for LLMs.
• Provide long‑term memory for AI assistants and chatbots.
• Centralize corporate knowledge bases and make them searchable.
• Power AI‑driven tools that need up‑to‑date information from PDFs, spreadsheets, and other docs.
• Enable semantic search across large document repositories.

FAQ

Q: Do I need to run the server locally?
A: No, you can use the hosted endpoint https://mcp.needle.app/mcp with your API key.

Q: Which LLMs are supported?
A: Designed for Claude Desktop, but any Model Context Protocol‑compatible client can connect.

Q: How is authentication handled?
A: By providing a Needle API key in the Authorization header (Bearer token).

Q: Can I run it in Docker?
A: Yes, build the Docker image and configure the client to invoke docker run --rm -i needle-mcp.

Q: What file types are indexed?
A: PDFs, DOCX, XLSX and other common document formats supported by Needle.

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

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

Usage Examples

• "Create a new collection called 'Technical Docs'"
• "Add this document to the collection, which is https://needle.app"
• "Search the collection for information about AI"
• "List all my collections"

Troubleshooting

If not working:

• Make sure uv is installed globally (if not, uninstall with pip uninstall uv and reinstall with brew install uv)
• Or find uv path with which uv and replace "command": "uv" with the full path
• Verify your Needle API key is correct
• Check if the needle-mcp path in config matches your actual repository location

Reset Claude Desktop Configuration

If you're seeing old configurations or the integration isn't working:

1. Find all Claude Desktop config files:

find / -name "claude_desktop_config.json" 2>/dev/null

2. Remove all Claude Desktop data:

• On MacOS: rm -rf ~/Library/Application\ Support/Claude/*
• On Windows: Delete contents of %APPDATA%/Claude/

3. Create a fresh config with only Needle:

mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json
<< 'EOL'
{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}
EOL

4. Completely quit Claude Desktop (Command+Q on Mac) and relaunch it

5. If you still see old configurations:

• Check for additional config files in other locations
• Try clearing browser cache if using web version
• Verify the config file is being read from the correct location