by needle-ai
Manages documents and enables semantic, natural‑language search for large language models, providing long‑term memory and Retrieval‑Augmented Generation capabilities.
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.
https://mcp.needle.app/mcp and supply your Needle API key.uv runner (or any Python environment), and run the needle-mcp entry point from the repository directory.The client configuration follows the same JSON shape for all three deployment options, only the command and args differ.
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.
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/sseNote: 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.jsonClaude 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>"
}
}
}
}claude mcp add needle npx mcp-remote https://mcp.needle.app/mcp --header Authorization:Bearer ${NEEDLE_API_KEY}Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
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.
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.
by smithery-ai
Provides read and search capabilities for Markdown notes in an Obsidian vault for Claude Desktop and other MCP clients.
by chatmcp
Summarize chat messages by querying a local chat database and returning concise overviews.
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.
by qdrant
Provides a Model Context Protocol server that stores and retrieves semantic memories using Qdrant vector search, acting as a semantic memory layer.
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.
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.