by needle-ai
Provides easy RAG and long‑term memory capabilities for large language models by managing documents and enabling semantic search via the Model Context Protocol.
Needle MCP enables LLMs to store, organize, and retrieve documents quickly, turning static files such as PDFs, DOCX, and XLSX into searchable knowledge that can be accessed through natural language queries.
npx mcp-remote https://mcp.needle.app/mcp --header "Authorization:Bearer ${NEEDLE_API_KEY}"
. Supply your Needle API key in the environment.uv
tool, and run the server with uv --directory /path/to/needle-mcp run needle-mcp
(or via Docker using the provided Dockerfile).docker build -t needle-mcp .
) and invoke it with docker run --rm -i needle-mcp
from the client configuration.Q: Do I need to run the server locally?
A: No, you can use the hosted endpoint https://mcp.needle.app/mcp
with your API key.
Q: Which LLMs are supported?
A: Designed for Claude Desktop, but any Model Context Protocol‑compatible client can connect.
Q: How is authentication handled?
A: By providing a Needle API key in the Authorization
header (Bearer token).
Q: Can I run it in Docker?
A: Yes, build the Docker image and configure the client to invoke docker run --rm -i needle-mcp
.
Q: What file types are indexed?
A: PDFs, DOCX, XLSX and other common document formats supported by Needle.
MCP (Model Context Protocol) server to manage documents and perform searches using Needle through Claude's Desktop Application.
Needle MCP Server allows you to:
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.
Below is an example of how the commands can be used in Claude Desktop to interact with the server:
https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c
For a full walkthrough on using the Needle MCP Server with Claude and Claude Desktop, watch this YouTube explanation video.
Claude Desktop Config
Create or update your config file:
~/Library/Application Support/Claude/claude_desktop_config.json
%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:
https://mcp.needle.app/mcp
(recommended)https://mcp.needle.app/sse
Note: MCP deprecated SSE endpoints in the latest specification, so newer clients should prefer the Streamable HTTP endpoint.
git clone https://github.com/needle-ai/needle-mcp.git
brew install uv
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%/Claude/claude_desktop_config.json
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>"
}
}
}
}
/path/to/needle-mcp
with your actual repository pathInstalling via Smithery
npx -y @smithery/cli install needle-mcp --client claude
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .
~/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>"
}
}
}
}
If not working:
uv
is installed globally (if not, uninstall with pip uninstall uv
and reinstall with brew install uv
)uv
path with which uv
and replace "command": "uv"
with the full pathIf you're seeing old configurations or the integration isn't working:
find / -name "claude_desktop_config.json" 2>/dev/null
rm -rf ~/Library/Application\ Support/Claude/*
%APPDATA%/Claude/
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:
Please log in to share your review and rating for this MCP.
{ "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>" } } } }
Discover more MCP servers with similar functionality and use cases
by topoteretes
Enables AI agents to store, retrieve, and reason over past conversations, documents, images, and audio transcriptions by loading data into graph and vector databases with minimal code.
by basicmachines-co
Basic Memory is a local-first knowledge management system that allows users to build a persistent semantic graph from conversations with AI assistants. It addresses the ephemeral nature of most LLM interactions by providing a structured, bi-directional knowledge base that both humans and LLMs can read and write to.
by smithery-ai
mcp-obsidian is a connector that allows Claude Desktop to read and search an Obsidian vault or any directory containing Markdown notes.
by qdrant
Provides a semantic memory layer on top of the Qdrant vector search engine, enabling storage and retrieval of information via the Model Context Protocol.
by GreatScottyMac
A database‑backed MCP server that stores project decisions, progress, architecture, custom data, and vector embeddings, allowing AI assistants in IDEs to retrieve precise, up‑to‑date context for generation tasks.
by StevenStavrakis
Enables AI assistants to read, create, edit, move, delete, and organize notes and tags within an Obsidian vault.
by mem0ai
Provides tools to store, retrieve, and semantically search coding preferences via an SSE endpoint for integration with MCP clients.
by graphlit
Enables integration between MCP clients and the Graphlit platform, providing ingestion, retrieval, RAG, and publishing capabilities across a wide range of data sources and tools.
by chroma-core
Provides vector, full‑text, and metadata‑based retrieval powered by Chroma for LLM applications, supporting in‑memory, persistent, HTTP, and cloud clients as well as multiple embedding functions.