JANHMS Needle MCP Server

🚀 Needle MCP Server for Claude

This is an MCP (Management Control Plane) server that manages documents and enables semantic search through Claude chat.

🚀 Quick Start

Example Usage

Example commands used in Claudie Desktop

How to set up this collection on Needle via Claude

Link to the resource

Quick Setup Guide

1. Clone the repository:

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

2. Install UV globally using Homebrew:

   brew install uv
   

3. Create the claude_desktop_config.json file:

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

4. Add the following 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. Obtain your API key from Needle.

6. Update the configuration file:

   • Replace /path/to/needle-mcp with the actual repository path.
   • Add your Needle API key.

7. Completely quit Claude and then reopen it.

💻 Usage Examples

Basic Usage

• "Create a new collection named 'Technical Docs'"
• "Add this document to the collection with the link https://needle-ai.com"
• "Search for information about AI in the collection"
• "List all my collections"

🔧 Troubleshooting

If it doesn't work properly:

• Make sure UV is installed globally. If not, uninstall it using pip uninstall uv and reinstall it using brew install uv.
• Or find the UV path and replace "command": "uv" in the configuration with the full path, e.g., $ which uv.
• Verify that your Needle API key is correct.
• Check if the needle-mcp path in the configuration file matches the actual repository location.

Resetting Claude Desktop Configuration

If you see old configurations or the integration doesn't work:

1. Find all Claude Desktop configuration files:

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

2. Delete all Claude Desktop data:

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

3. Create a new configuration containing 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