Skip to main content

Build AI Agents with MCP + Needle

Claude Symbol

GitHub Repository

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

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

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

Installation​

  1. Clone the repository:
git clone https://github.com/JANHMS/needle-mcp.git
  1. Install UV globally using Homebrew in Terminal:
brew install uv

  1. Create claude_desktop_config.json:

    • For MacOS: Open directory ~/Library/Application Support/Claude/ and create the file inside it
    • For Windows: Open directory %APPDATA%/Claude/ and create the file inside it

  2. 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"
      }
    }
  }
}

  1. Get your Needle API key from needle-ai.com

  2. Update the config file:

    • Replace /path/to/needle-mcp with your actual repository path
    • Add your Needle API key
    • Quit Claude completely and reopen it

Usage Examples​

You can use these commands in Claude Desktop:

  • "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:

  1. Make sure UV is installed globally (if not, uninstall with pip uninstall uv and reinstall with brew install uv)
  2. Or find UV path with which uv and replace "command": "uv" with the full path
  3. Verify your Needle API key is correct
  4. 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

  1. Remove all Claude Desktop data:

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

  2. 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
  1. Completely quit Claude Desktop (Command+Q on Mac) and relaunch it

If you still see old configurations:

  • Check for additional config files in other locations

Support​

If you have any questions or need help with the integration, feel free to:

Video Demo: Building AI Agents with Needle MCP​

Watch this video to see Needle MCP in action:

This demonstration shows how to:

  • Set up the Needle MCP server with Claude Desktop
  • Create and manage collections
  • Perform natural language searches
  • Use knowledge threading for enhanced document retrieval