Needle MCP Server
Featuredby
Manages documents and enables semantic, natural‑language search for large language models, providing long‑term memory and Retrieval‑Augmented Generation capabilities.
Needle MCP Server Overview
What is Needle MCP Server about?
Needle MCP Server offers a lightweight backend that stores collections of PDFs, DOCX, XLSX and other files, exposing them through the Model Context Protocol. LLMs such as Claude can query the server with plain English and receive relevant passages, turning unstructured data into instantly searchable knowledge.
How to use Needle MCP Server?
- Remote (recommended) – Add the server entry to Claude Desktop or Cursor config, pointing to the hosted endpoint
https://mcp.needle.app/mcpand supply your Needle API key. - Local – Clone the repo, install the
uvrunner (or any Python environment), and run theneedle-mcpentry point from the repository directory. - Docker – Build the provided Dockerfile and run the container as the command for the MCP entry.
The client configuration follows the same JSON shape for all three deployment options, only the command and args differ.
Key Features
- Document Management – Add, organize, and list collections via simple MCP commands.
- Claude‑powered Semantic Search – Natural‑language queries are interpreted by Claude and mapped to relevant document snippets.
- Multiple Deployment Modes – Remote hosted service, local source run, or Docker container.
- Easy Integration – Works out‑of‑the‑box with Claude Desktop, Cursor, and any MCP‑compatible client.
- Support for Common File Types – PDFs, DOCX, XLSX, etc.
Use Cases
- Building RAG‑enabled assistants that need persistent access to internal knowledge bases.
- Providing instant lookup for technical documentation, policy manuals, or research papers.
- Enabling enterprise LLMs to answer questions without re‑training on proprietary data.
- Rapid prototyping of AI agents that require contextual awareness of user‑uploaded files.
FAQ
Q: Do I need to run the server locally?
A: No. The hosted endpoint (https://mcp.needle.app/mcp) works for most scenarios and requires only an API key.
Q: Which command should I use in the config?
A: Prefer npx mcp-remote for the remote service; for local runs use uv or Docker as shown in the installation section.
Q: What environment variable holds the API key?
A: NEEDLE_API_KEY (or NEEDLE_AUTH_HEADER for a full Bearer … header).
Q: Can I switch between Streamable HTTP and SSE endpoints? A: Yes, but the latest specification deprecates SSE, so the Streamable HTTP endpoint is recommended.
Q: How do I reset Claude Desktop configuration?
A: Delete existing claude_desktop_config.json files, recreate a fresh config containing only the Needle MCP entry, and restart the application.
Needle MCP Server's README
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
{
"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
- Clone the repository:
git clone https://github.com/needle-ai/needle-mcp.git
- Install UV globally using Homebrew:
brew install uv
- 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
{
"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>"
}
}
}
}
- Replace
/path/to/needle-mcpwith your actual repository path - Add your Needle API key
- Restart Claude Desktop
Installing via Smithery
npx -y @smithery/cli install needle-mcp --client claude
3. Docker Installation
- Clone and build:
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .
- 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>"
}
}
}
}
- 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
uvis installed globally (if not, uninstall withpip uninstall uvand reinstall withbrew install uv) - Or find
uvpath withwhich uvand 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:
find / -name "claude_desktop_config.json" 2>/dev/null
- 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:
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
-
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
Needle MCP Server Reviews
Login Required
Please log in to share your review and rating for this MCP.
Actions
Needle MCP Server's Information
- Author
- needle-ai
- Category
- Knowledge & Memory
- Language
- Python
- License
- MIT License
- Stars
- 81
- Updated
- 1 month ago
Configuration
{
"mcpServers": {
"needle": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.needle.app/mcp",
"--header",
"Authorization:Bearer ${NEEDLE_API_KEY}"
],
"env": {
"NEEDLE_API_KEY": "<YOUR_API_KEY>"
}
}
}
}Claude Code (Terminal)
claude mcp add needle npx mcp-remote https://mcp.needle.app/mcp --header Authorization:Bearer ${NEEDLE_API_KEY}Configure Clients
Similar MCP Servers like Needle MCP Server
Explore related MCPs that share similar capabilities and solve comparable challenges
Memory
Officialby modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
Cognee
by topoteretes
Provides dynamic memory for AI agents through modular ECL (Extract, Cognify, Load) pipelines, enabling seamless integration with graph and vector stores using minimal code.
Basic Memory
by basicmachines-co
Enables persistent, local‑first knowledge management by allowing LLMs to read and write Markdown files during natural conversations, building a traversable knowledge graph that stays under the user’s control.
Obsidian Model Context Protocol
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
Mcp Server Chatsum
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
Minima
by dmayboroda
Provides on‑premises conversational retrieval‑augmented generation (RAG) with configurable Docker containers, supporting fully local execution, ChatGPT‑based custom GPTs, and Anthropic Claude integration.
Mcp Server Qdrant
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
MCP Memory Service
by doobidoo
Provides a universal memory service with semantic search, intelligent memory triggers, OAuth‑enabled team collaboration, and multi‑client support for Claude Desktop, Claude Code, VS Code, Cursor and over a dozen AI applications.
Context Portal
by GreatScottyMac
Provides a project‑specific memory bank that stores decisions, progress, architecture, and custom data, exposing a structured knowledge graph via MCP for AI assistants and IDE tools.