Skip to main content
Glama
Needle MCP Server

Needle MCP Server

Official
by needle-ai

Crear agentes con Needle MCP Server

insignia de herrería

Captura de pantalla de Feature - Claude

Servidor MCP (Model Context Protocol) para gestionar documentos y realizar búsquedas utilizando Needle a través de la aplicación de escritorio de Claude.

Tabla de contenido


Related MCP server: Documentation MCP Server

Descripción general

El servidor Needle MCP le permite:

  • Organice y almacene documentos para una rápida recuperación.

  • Realice búsquedas potentes a través del gran modelo de lenguaje de Claude.

  • Se integra perfectamente con el ecosistema Needle para una gestión avanzada de documentos.


Características

  • Gestión de documentos: agregue y organice documentos fácilmente en el servidor.

  • Búsqueda y recuperación: búsqueda en lenguaje natural basada en Claude para obtener respuestas rápidas.

  • Fácil integración: funciona con las colecciones Claude Desktop y Needle.


Uso

Comandos en Claude Desktop

A continuación se muestra un ejemplo de cómo se pueden utilizar los comandos en Claude Desktop para interactuar con el servidor:

Uso de comandos en Claude Desktop

  1. Abra Claude Desktop y conéctese al servidor Needle MCP.

  2. Utilice comandos de texto simples para buscar, recuperar o modificar documentos.

  3. Revise los resultados de búsqueda devueltos por Claude en una interfaz fácil de usar.

Resultado en Aguja

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


Explicación del vídeo de YouTube

Para obtener una guía completa sobre el uso del servidor Needle MCP con Claude y Claude Desktop, mire este video explicativo de YouTube .


Instalación

Instalación mediante herrería

Para instalar Needle MCP para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install needle-mcp --client claude

Instalación manual

  1. Clonar el repositorio:

git clone https://github.com/yourusername/needle-mcp.git
  1. Instalar UV globalmente usando Homebrew en la Terminal:

brew install uv
  1. Crear claude_desktop_config.json:

    • Para MacOS: Abra el directorio ~/Library/Application Support/Claude/ y cree el archivo dentro de él

    • Para Windows: Abra el directorio %APPDATA%/Claude/ y cree el archivo dentro de él

  2. Agregue esta configuración a 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. Obtén tu clave API de Needle en needle.xyz

  2. Actualice el archivo de configuración:

    • Reemplace /path/to/needle-mcp con su ruta de repositorio real

    • Añade tu clave API de Needle

  3. Salga de Claude por completo y vuelva a abrirlo.

Ejemplos de uso

  • "Crear una nueva colección llamada 'Documentos técnicos'"

  • Añade este documento a la colección, que es https://needle-ai.com

  • "Buscar información sobre IA en la colección"

  • "Enumerar todas mis colecciones"

Solución de problemas

Si no funciona:

  • Asegúrese de que UV esté instalado globalmente (si no, desinstálelo con pip uninstall uv y vuelva a instalarlo con brew install uv )

  • O busque la ruta UV con which uv y reemplace "command": "uv" con la ruta completa

  • Verifique que su clave API de Needle sea correcta

  • Comprueba si la ruta needle-mcp en la configuración coincide con la ubicación real de tu repositorio

Restablecer la configuración del escritorio de Claude

Si ves configuraciones antiguas o la integración no funciona:

  1. Encuentra todos los archivos de configuración de Claude Desktop:

find / -name "claude_desktop_config.json" 2>/dev/null
  1. Eliminar todos los datos de Claude Desktop:

  • En MacOS: rm -rf ~/Library/Application\ Support/Claude/*

  • En Windows: eliminar el contenido de %APPDATA%/Claude/

  1. Crea una nueva configuración solo con 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. Cierre completamente Claude Desktop (Comando+Q en Mac) y reinícielo

  2. Si aún ves configuraciones antiguas:

  • Busque archivos de configuración adicionales en otras ubicaciones

  • Intente borrar el caché del navegador si usa la versión web

  • Verifique que el archivo de configuración se esté leyendo desde la ubicación correcta

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