Skip to main content
Glama
Needle MCP Server

Needle MCP Server

Official
by needle-ai

Needle MCP 서버를 사용하여 에이전트 빌드

대장간 배지

기능 스크린샷 - Claude

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에서 명령 사용

  1. Claude Desktop을 열고 Needle MCP 서버에 연결합니다.

  2. 간단한 텍스트 명령을 사용하여 문서를 검색, 꺼내오거나 수정합니다.

  3. 사용자 친화적인 인터페이스에서 클로드가 반환한 검색 결과를 검토하세요 .

바늘에 결과

https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c


유튜브 영상 설명

Claude와 Claude Desktop에서 Needle MCP 서버를 사용하는 방법에 대한 전체적인 연습을 보려면 이 YouTube 설명 비디오를 시청하세요.


설치

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop용 Needle MCP를 자동으로 설치하려면:

지엑스피1

수동 설치

  1. 저장소를 복제합니다.

git clone https://github.com/yourusername/needle-mcp.git
  1. 터미널에서 Homebrew를 사용하여 UV를 전역적으로 설치하세요.

brew install uv
  1. claude_desktop_config.json을 생성합니다.

    • MacOS의 경우: ~/Library/Application Support/Claude/ 디렉토리를 열고 그 안에 파일을 만듭니다.

    • Windows의 경우: %APPDATA%/Claude/ 디렉토리를 열고 그 안에 파일을 만듭니다.

  2. 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"
      }
    }
  }
}
  1. needle.xyz에서 Needle API 키를 받으세요

  2. 구성 파일을 업데이트합니다.

    • /path/to/needle-mcp 실제 저장소 경로로 바꾸세요.

    • Needle API 키를 추가하세요

  3. Claude를 완전히 종료하고 다시 열어보세요.

사용 예

  • "'기술 문서'라는 새 컬렉션을 만듭니다."

  • "이 문서를 https://needle-ai.com 컬렉션에 추가하세요."

  • "AI에 대한 정보를 컬렉션에서 검색하세요"

  • "내 모든 컬렉션 나열"

문제 해결

작동하지 않는 경우:

  • UV가 전역적으로 설치되어 있는지 확인하세요(그렇지 않은 경우 pip uninstall uv 로 제거하고 brew install uv 로 다시 설치하세요)

  • 또는 which uv 포함된 UV 경로를 찾아 "command": "uv" 전체 경로로 바꾸세요.

  • Needle API 키가 올바른지 확인하세요

  • config의 needle-mcp 경로가 실제 저장소 위치와 일치하는지 확인하세요.

Claude 데스크톱 구성 재설정

이전 구성이 표시되거나 통합이 작동하지 않는 경우:

  1. 모든 Claude Desktop 구성 파일을 찾으세요:

find / -name "claude_desktop_config.json" 2>/dev/null
  1. 모든 Claude Desktop 데이터를 제거합니다.

  • MacOS의 경우: rm -rf ~/Library/Application\ Support/Claude/*

  • Windows에서: %APPDATA%/Claude/ 의 내용을 삭제합니다.

  1. 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"
      }
    }
  }
}
EOL
  1. Claude Desktop을 완전히 종료하고(Mac에서는 Command+Q) 다시 시작합니다.

  2. 여전히 이전 구성이 표시되는 경우:

  • 다른 위치에 추가 구성 파일이 있는지 확인하세요.

  • 웹 버전을 사용하는 경우 브라우저 캐시를 지워보세요.

  • 구성 파일이 올바른 위치에서 읽혀지고 있는지 확인하세요.

Available Tools

7 tools
needle_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).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers