{"id":26648605,"url":"https://github.com/needle-ai/needle-mcp","last_synced_at":"2026-06-26T22:01:49.770Z","repository":{"id":268252604,"uuid":"903772115","full_name":"needle-ai/needle-mcp","owner":"needle-ai","description":"Needle MCP Server for easy RAG.Long-term memory for LLMs.","archived":false,"fork":false,"pushed_at":"2025-07-27T13:34:24.000Z","size":51,"stargazers_count":86,"open_issues_count":2,"forks_count":23,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-12-04T04:14:24.787Z","etag":null,"topics":["ai","mcp","modelcontextprotocol","rag","semantic-search"],"latest_commit_sha":null,"homepage":"https://needle.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/needle-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-15T14:25:13.000Z","updated_at":"2025-12-01T22:15:54.000Z","dependencies_parsed_at":"2025-01-13T12:22:05.619Z","dependency_job_id":"c31096d2-7c90-40c6-a1b3-dcc78953489e","html_url":"https://github.com/needle-ai/needle-mcp","commit_stats":null,"previous_names":["janhms/needle-mcp-server","janhms/needle-mcp","needle-ai/needle-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/needle-ai/needle-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/needle-ai","download_url":"https://codeload.github.com/needle-ai/needle-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-ai%2Fneedle-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mcp","modelcontextprotocol","rag","semantic-search"],"created_at":"2025-03-25T00:02:11.052Z","updated_at":"2026-06-26T22:01:49.763Z","avatar_url":"https://github.com/needle-ai.png","language":"Python","funding_links":[],"categories":["AI Memory \u0026 RAG","MCP 服务器精选列表","Production-Ready Servers","Search","Official Servers","官方 MCP 服务器列表","Other Tools and Integrations","Python","Document Processing","Mcp Server Directories \u0026 Lists","📦 Other","Table of Contents","🗂️ Extensions by Category","Knowledge \u0026 Memory"],"sub_categories":["RAG","🧠 知识、记忆与 RAG","How to Submit","Other Tools and Integrations","🧠 Knowledge Base"],"readme":"# Build Agents with Needle MCP Server\n\n[![smithery badge](https://smithery.ai/badge/needle-mcp)](https://smithery.ai/server/needle-mcp)\n\n![Screenshot of Feature - Claude](https://github.com/user-attachments/assets/a7286901-e7be-4efe-afd9-72021dce03d4)\n\nMCP (Model Context Protocol) server to manage documents and perform searches using [Needle](https://needle.app) through Claude's Desktop Application.\n\n\u003ca href=\"https://glama.ai/mcp/servers/5jw1t7hur2\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/5jw1t7hur2/badge\" alt=\"Needle Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Usage](#usage)\n  - [Commands in Claude Desktop](#commands-in-claude-desktop)\n  - [Result in Needle](#result-in-needle)\n- [Installation](#installation)\n- [Video Explanation](#youtube-video-explanation)\n\n---\n\n## Overview\n\nNeedle MCP Server allows you to:\n\n- Organize and store documents for quick retrieval.\n- Perform powerful searches via Claude's large language model.\n- Integrate seamlessly with the Needle ecosystem for advanced document management.\n\nMCP (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.\n\n**We recommend using our remote MCP server** for the best experience - no local setup required.\n\n---\n\n## Features\n\n- **Document Management:** Easily add and organize documents on the server.\n- **Search \u0026 Retrieval:** Claude-based natural language search for quick answers.\n- **Easy Integration:** Works with [Claude Desktop](#commands-in-claude-desktop) and Needle collections.\n\n---\n\n## Usage\n\n### Commands in Claude Desktop\n\nBelow is an example of how the commands can be used in Claude Desktop to interact with the server:\n\n![Using commands in Claude Desktop](https://github.com/user-attachments/assets/9e0ce522-6675-46d9-9bfb-3162d214625b)\n\n1. **Open Claude Desktop** and connect to the Needle MCP Server.  \n2. **Use simple text commands** to search, retrieve, or modify documents.  \n3. **Review search results** returned by Claude in a user-friendly interface.\n\n### Result in Needle\n\nhttps://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c\n\n---\n\n## Youtube Video Explanation\n\nFor a full walkthrough on using the Needle MCP Server with Claude and Claude Desktop, watch this [YouTube explanation video](https://youtu.be/nVrRYp9NZYg).\n\n---\n\n## Installation\n\n### 1. Remote MCP Server (Recommended)\n\n**Claude Desktop Config**\n\nCreate or update your config file:\n- For MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- For Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp.needle.app/mcp\",\n        \"--header\",\n        \"Authorization:Bearer ${NEEDLE_API_KEY}\"\n      ],\n      \"env\": {\n        \"NEEDLE_API_KEY\": \"\u003cyour-needle-api-key\u003e\"\n      }\n    }\n  }\n}\n```\n\n**Cursor Config**\n\nCreate or update `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https://mcp.needle.app/mcp\",\n        \"--header\",\n        \"Authorization:${NEEDLE_AUTH_HEADER}\"\n      ],\n      \"env\": {\n        \"NEEDLE_AUTH_HEADER\": \"Bearer \u003cyour-needle-api-key\u003e\"\n      }\n    }\n  }\n}\n```\n\nGet your API key from [Needle Settings](https://needle.app).\n\nWe provide two endpoints:\n- **Streamable HTTP**: `https://mcp.needle.app/mcp` (recommended)\n- **SSE**: `https://mcp.needle.app/sse`\n\nNote: MCP deprecated SSE endpoints in the latest specification, so newer clients should prefer the Streamable HTTP endpoint.\n\n### 2. Local Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/needle-ai/needle-mcp.git\n```\n\n2. Install UV globally using Homebrew:\n```bash\nbrew install uv\n```\n\n3. Create your config file:\n   - For MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - For Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n**Claude Desktop Config**\n\n```json\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/needle-mcp\", \"run\", \"needle-mcp\"],\n      \"env\": {\n        \"NEEDLE_API_KEY\": \"\u003cyour-needle-api-key\u003e\"\n      }\n    }\n  }\n}\n```\n\n**Cursor Config**\n\n```json\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/needle-mcp\", \"run\", \"needle-mcp\"],\n      \"env\": {\n        \"NEEDLE_API_KEY\": \"\u003cyour-needle-api-key\u003e\"\n      }\n    }\n  }\n}\n```\n\n4. Replace `/path/to/needle-mcp` with your actual repository path\n5. Add your Needle API key\n6. Restart Claude Desktop\n\n**Installing via Smithery**\n\n```bash\nnpx -y @smithery/cli install needle-mcp --client claude\n```\n\n### 3. Docker Installation\n\n1. Clone and build:\n```bash\ngit clone https://github.com/needle-ai/needle-mcp.git\ncd needle-mcp\ndocker build -t needle-mcp .\n```\n\n2. Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"needle-mcp\"],\n      \"env\": {\n        \"NEEDLE_API_KEY\": \"\u003cyour-needle-api-key\u003e\"\n      }\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop\n\n## Usage Examples\n\n* \"Create a new collection called 'Technical Docs'\"\n* \"Add this document to the collection, which is https://needle.app\"\n* \"Search the collection for information about AI\"\n* \"List all my collections\"\n\n## Troubleshooting\n\nIf not working:\n- Make sure `uv` is installed globally (if not, uninstall with `pip uninstall uv` and reinstall with `brew install uv`)\n- Or find `uv` path with `which uv` and replace `\"command\": \"uv\"` with the full path\n- Verify your Needle API key is correct\n- Check if the needle-mcp path in config matches your actual repository location\n\n### Reset Claude Desktop Configuration\n\nIf you're seeing old configurations or the integration isn't working:\n\n1. Find all Claude Desktop config files:\n```bash\nfind / -name \"claude_desktop_config.json\" 2\u003e/dev/null\n```\n\n2. Remove all Claude Desktop data:\n- On MacOS: `rm -rf ~/Library/Application\\ Support/Claude/*`\n- On Windows: Delete contents of `%APPDATA%/Claude/`\n\n3. Create a fresh config with only Needle:\n```\nmkdir -p ~/Library/Application\\ Support/Claude\ncat \u003e ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n\u003c\u003c 'EOL'\n{\n  \"mcpServers\": {\n    \"needle\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/needle-mcp\",\n        \"run\",\n        \"needle-mcp\"\n      ],\n      \"env\": {\n        \"NEEDLE_API_KEY\": \"your_needle_api_key\"\n      }\n    }\n  }\n}\nEOL\n```\n\n4. Completely quit Claude Desktop (Command+Q on Mac) and relaunch it\n\n5. If you still see old configurations:\n- Check for additional config files in other locations\n- Try clearing browser cache if using web version\n- Verify the config file is being read from the correct location\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-ai%2Fneedle-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneedle-ai%2Fneedle-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-ai%2Fneedle-mcp/lists"}