The Needle MCP Server enables efficient document organization, retrieval, and semantic search using Claude's large language model and the Needle ecosystem.
- Document Management: Add, organize, and retrieve documents efficiently
- Collection Operations: Create, list, and manage document collections with detailed metadata and statistics
- File Operations: Add files via URLs and monitor processing status
- Semantic Search: Perform advanced natural language searches to find conceptually related content within document collections
- Integration: Seamlessly integrate with Claude Desktop and Needle for enhanced document handling
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
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:
- Open Claude Desktop and connect to the Needle MCP Server.
- Use simple text commands to search, retrieve, or modify documents.
- 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
Cursor Config
Create or update .cursor/mcp.json
:
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
- Clone the repository:
- Install UV globally using Homebrew:
- Create your config file:
- For MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- For Windows:
%APPDATA%/Claude/claude_desktop_config.json
- For MacOS:
Claude Desktop Config
Cursor Config
- Replace
/path/to/needle-mcp
with your actual repository path - Add your Needle API key
- Restart Claude Desktop
Installing via Smithery
3. Docker Installation
- Clone and build:
- Add to your Claude Desktop config (
~/Library/Application Support/Claude/claude_desktop_config.json
):
- 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 withpip uninstall uv
and reinstall withbrew install uv
) - Or find
uv
path withwhich 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:
- Find all Claude Desktop config files:
- Remove all Claude Desktop data:
- On MacOS:
rm -rf ~/Library/Application\ Support/Claude/*
- On Windows: Delete contents of
%APPDATA%/Claude/
- Create a fresh config with only Needle:
- 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
- Try clearing browser cache if using web version
- Verify the config file is being read from the correct location
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
A server that allows users to manage documents and perform Claude-powered searches using Needle through the Claude Desktop application.
- Table of Contents
- Overview
- Features
- Usage
- Youtube Video Explanation
- Installation
- Usage Examples
- Troubleshooting
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityThis server enables interaction between Neo4j databases and Claude Desktop, allowing users to execute Cypher queries, create nodes, and establish relationships in the database.Last updated -310453TypeScriptMIT License
- AsecurityAlicenseAqualityA server that integrates with Claude Desktop to enable real-time web research capabilities, allowing users to search Google, extract webpage content, and capture screenshots directly from conversations.Last updated -3859MIT License
- AsecurityAlicenseAqualityA server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.Last updated -1923,9714MIT License
- -securityFlicense-qualityA Model Control Protocol server that provides web search capabilities and similarity search functionality for Claude Desktop, allowing users to perform web searches and extract relevant information from previous search results.Last updated -2Python