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 Claudie Desktop
  • Result in Needle
• Installation
• Video Explanation

Overview

Needle MCP Server enables document organization, storage, and powerful searches using Claude’s large language model, integrating seamlessly with the Needle ecosystem.

Features

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

Usage

Commands in Claudie Desktop

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

1. Open Claudie 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

Installation

1. Clone the repository:

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

2. Install UV globally using Homebrew in Terminal:

brew install uv

3. Create claude_desktop_config.json:
   • MacOS: ~/Library/Application Support/Claude/
   • Windows: %APPDATA%/Claude/
4. Add this configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "needle_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}

5. Get your Needle API key from needle.xyz
6. Update the config file:
   • Replace /path/to/needle-mcp with your repository path.
   • Add your Needle API key.
7. Quit and reopen Claude.

Usage Examples

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

Troubleshooting

If not working:

• Ensure UV is globally installed (reinstall with brew install uv).
• Or, use which uv to find UV path and update the config.
• Verify your Needle API key.
• Check the needle-mcp path in the config.

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:

• MacOS: rm -rf ~/Library/Application\ Support/Claude/*
• 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_mcp": {
      "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

Youtube Video Explanation

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