Needle MCP Server
OfficialNeedle MCP 서버를 사용하여 에이전트 빌드
Claude의 데스크톱 애플리케이션을 통해 Needle을 사용하여 문서를 관리하고 검색을 수행하는 MCP(Model Context Protocol) 서버입니다.
목차
Related MCP server: Documentation MCP Server
개요
Needle MCP 서버를 사용하면 다음 작업을 수행할 수 있습니다.
빠른 검색을 위해 문서를 정리하고 보관하세요.
클로드의 대규모 언어 모델을 통해 강력한 검색을 수행합니다.
고급 문서 관리를 위해 Needle 생태계와 완벽하게 통합됩니다.
특징
문서 관리: 서버에서 문서를 쉽게 추가하고 정리할 수 있습니다.
검색 및 불러오기: 빠른 답변을 위한 Claude 기반 자연어 검색.
간편한 통합: Claude Desktop 및 Needle 컬렉션과 호환됩니다.
용법
Claude Desktop의 명령
다음은 Claude Desktop에서 명령을 사용하여 서버와 상호 작용하는 방법의 예입니다.
Claude Desktop을 열고 Needle MCP 서버에 연결합니다.
간단한 텍스트 명령을 사용하여 문서를 검색, 꺼내오거나 수정합니다.
사용자 친화적인 인터페이스에서 클로드가 반환한 검색 결과를 검토하세요 .
바늘에 결과
https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c
유튜브 영상 설명
Claude와 Claude Desktop에서 Needle MCP 서버를 사용하는 방법에 대한 전체적인 연습을 보려면 이 YouTube 설명 비디오를 시청하세요.
설치
Smithery를 통해 설치
Smithery 를 통해 Claude Desktop용 Needle MCP를 자동으로 설치하려면:
지엑스피1
수동 설치
저장소를 복제합니다.
git clone https://github.com/yourusername/needle-mcp.git터미널에서 Homebrew를 사용하여 UV를 전역적으로 설치하세요.
brew install uvclaude_desktop_config.json을 생성합니다.
MacOS의 경우:
~/Library/Application Support/Claude/디렉토리를 열고 그 안에 파일을 만듭니다.Windows의 경우:
%APPDATA%/Claude/디렉토리를 열고 그 안에 파일을 만듭니다.
claude_desktop_config.json에 이 구성을 추가합니다.
{
"mcpServers": {
"needle_mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/needle-mcp",
"run",
"needle-mcp"
],
"env": {
"NEEDLE_API_KEY": "your_needle_api_key"
}
}
}
}needle.xyz에서 Needle API 키를 받으세요
구성 파일을 업데이트합니다.
/path/to/needle-mcp실제 저장소 경로로 바꾸세요.Needle API 키를 추가하세요
Claude를 완전히 종료하고 다시 열어보세요.
사용 예
"'기술 문서'라는 새 컬렉션을 만듭니다."
"이 문서를 https://needle-ai.com 컬렉션에 추가하세요."
"AI에 대한 정보를 컬렉션에서 검색하세요"
"내 모든 컬렉션 나열"
문제 해결
작동하지 않는 경우:
UV가 전역적으로 설치되어 있는지 확인하세요(그렇지 않은 경우
pip uninstall uv로 제거하고brew install uv로 다시 설치하세요)또는
which uv포함된 UV 경로를 찾아"command": "uv"전체 경로로 바꾸세요.Needle API 키가 올바른지 확인하세요
config의 needle-mcp 경로가 실제 저장소 위치와 일치하는지 확인하세요.
Claude 데스크톱 구성 재설정
이전 구성이 표시되거나 통합이 작동하지 않는 경우:
모든 Claude Desktop 구성 파일을 찾으세요:
find / -name "claude_desktop_config.json" 2>/dev/null모든 Claude Desktop 데이터를 제거합니다.
MacOS의 경우:
rm -rf ~/Library/Application\ Support/Claude/*Windows에서:
%APPDATA%/Claude/의 내용을 삭제합니다.
Needle만 사용하여 새로운 구성을 만듭니다.
mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json
<< 'EOL'
{
"mcpServers": {
"needle_mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/needle-mcp",
"run",
"needle-mcp"
],
"env": {
"NEEDLE_API_KEY": "your_needle_api_key"
}
}
}
}
EOLClaude Desktop을 완전히 종료하고(Mac에서는 Command+Q) 다시 시작합니다.
여전히 이전 구성이 표시되는 경우:
다른 위치에 추가 구성 파일이 있는지 확인하세요.
웹 버전을 사용하는 경우 브라우저 캐시를 지워보세요.
구성 파일이 올바른 위치에서 읽혀지고 있는지 확인하세요.
Available Tools
7 toolsneedle_add_fileAInspect
Add a new document to a Needle collection by providing a URL for download. Supports multiple file formats including: - PDF documents - Microsoft Word files (DOC, DOCX) - Plain text files (TXT) - Web pages (HTML)
The document will be:
1. Downloaded from the provided URL
2. Processed for text extraction
3. Indexed for semantic search
Use this tool when you need to:
- Add new documents to a collection
- Make documents searchable
- Expand your knowledge base
Important: Documents require processing time before they're searchable.
Check processing status using needle_list_files before searching new content.Inputs: collection_id (required), name (required), url (required).
needle_create_collectionAInspect
Create a new document collection in Needle for organizing and searching documents. A collection acts as a container for related documents and enables semantic search across its contents. Use this tool when you need to: - Start a new document organization - Group related documents together - Set up a searchable document repository Returns a collection ID that's required for subsequent operations. Choose a descriptive name that reflects the collection's purpose for better organization.
Inputs: name (required).
needle_get_collection_detailsAInspect
Fetch comprehensive metadata about a specific Needle collection. Provides detailed information about the collection's configuration, creation date, and current status. Use this tool when you need to: - Verify a collection's existence and configuration - Check collection metadata before operations - Get creation date and other attributes Requires a valid collection ID and returns detailed collection metadata. Will error if collection doesn't exist.
Inputs: collection_id (required).
needle_get_collection_statsAInspect
Retrieve detailed statistical information about a Needle collection's contents and status. Provides metrics including: - Total number of documents - Processing status of documents - Storage usage and limits - Index status and health Use this tool to: - Monitor collection size and growth - Verify processing completion - Check collection health before operations Essential for ensuring collection readiness before performing searches.
Inputs: collection_id (required).
needle_list_collectionsAInspect
List Needle collections. Returns maximum of 20 results. Get more results by increasing the offset. Returns detailed information including collection IDs, names, and creation dates. Use this tool when you need to: - Get an overview of available document collections - Find collection IDs for subsequent operations - Verify collection existence before performing operations The response includes metadata that's required for other Needle operations.
Inputs: offset.
needle_list_filesAInspect
List all documents stored within a specific Needle collection with their current status. Returns detailed information about each file including: - File ID and name - Processing status (pending, processing, complete, error) - Upload date and metadata Use this tool when you need to: - Inventory available documents - Check processing status of uploads - Get file IDs for reference - Verify document availability before searching Essential for monitoring document processing completion before performing searches.
Inputs: collection_id (required).
needle_searchAInspect
Perform intelligent semantic search across documents in a Needle collection. This tool uses advanced embedding technology to find relevant content based on meaning, not just keywords. The search: - Understands natural language queries - Finds conceptually related content - Returns relevant text passages with source information - Ranks results by semantic relevance
Use this tool when you need to:
- Find specific information within documents
- Answer questions from document content
- Research topics across multiple documents
- Locate relevant passages and their sources
More effective than traditional keyword search for:
- Natural language questions
- Conceptual queries
- Finding related content
Returns matching text passages with their source file IDs.Inputs: collection_id (required), query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose with no overlap: collection management (create, list, get details, get stats), file management (add, list), and search. The descriptions explicitly differentiate their functions, such as needle_get_collection_details for metadata vs. needle_get_collection_stats for metrics, eliminating any ambiguity.
All tools follow a consistent verb_noun pattern with the 'needle_' prefix, using snake_case throughout (e.g., needle_create_collection, needle_list_files). This predictable naming scheme makes it easy for agents to understand and select tools based on their actions and targets.
With 7 tools, the server is well-scoped for document management and search, covering essential operations like collection CRUD, file addition, status monitoring, and semantic search. Each tool serves a clear purpose without redundancy, fitting the domain's needs efficiently.
The toolset provides strong coverage for core document management workflows, including collection lifecycle, file processing, and search. A minor gap exists in file deletion or update capabilities, which could limit full CRUD operations, but agents can still perform key tasks like adding, listing, and searching documents effectively.
Maintenance
Related MCP Connectors
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Pageform is an AI-native data room platform with a remote MCP server for Claude and other MCP-compatible clients. Upload and organize documents, generate structured data rooms with AI, audit missing materials, create secure share links, and analyze investor engagement directly from your AI assistant. Built for fundraising, investor relations, diligence, and deal workflows. Connect securely through Pageform OAuth. Website: https://pageform.io Documentation: https://pageform.io/docs/integrations/claude
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceA server that connects Claude to your documentation via Inkeep's API, enabling AI-powered interactions with your documentation content.25MIT- FlicenseAqualityDmaintenanceA server that enables Claude to search and access documentation from popular libraries like LangChain, LlamaIndex, and OpenAI directly within conversations.13-
- FlicenseNot gradedqualityDmaintenanceA local document intelligence and knowledge management server for Claude Desktop that provides RAG-powered Q\&A, media transcription, and URL crawling. It features 11 tools for processing various file types and managing a persistent local vector store with zero infrastructure costs.1-
- FlicenseNot gradedqualityDmaintenanceMCP server enabling Claude Desktop to answer questions from local Word and PDF documents by searching a vector index built from their contents.-