Needle

Needle MCP Server

Production-ready RAG service to search and retrieve data from your documents.

What is an MCP Server?⁠

MCP Info

Image Building Info

Attribute	Details
Dockerfile	https://github.com/needle-ai/needle-mcp/blob/96d82632e3c719ffa61dc8f0909a7cc0d185a161/Dockerfile⁠
Commit	96d82632e3c719ffa61dc8f0909a7cc0d185a161
Docker Image built by	Docker Inc.
Docker Scout Health Score
Verify Signature	COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/needle-mcp --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub
Licence	MIT License

Available Tools (7)

Tools Details

Tool: needle_add_file

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.

Tool: needle_create_collection

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.

Tool: needle_get_collection_details

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.

Tool: needle_get_collection_stats

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.

Tool: needle_list_collections

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.

Tool: needle_list_files

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.

Tool: needle_search

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.

Use this MCP Server

{
  "mcpServers": {
    "needle-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEEDLE_API_KEY",
        "mcp/needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your-needle-api-key-here"
      }
    }
  }
}

Why is it safer to run MCP Servers with Docker?⁠