Needle MCP Server

oficial

RAG listo para producción para buscar y recuperar datos de tus propios documentos.

GitHub
99

Documentación

Construye Agentes con el Servidor MCP de Needle

smithery badge

Screenshot of Feature - Claude

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

Needle Server MCP server

Tabla de Contenidos

Descripción General

El Servidor MCP de Needle te permite:

  • Organizar y almacenar documentos para una recuperación rápida.
  • Realizar búsquedas potentes a través del modelo de lenguaje extenso de Claude.
  • Integrarte sin problemas con el ecosistema de Needle para una gestión avanzada de documentos.

MCP (Model Context Protocol) estandariza la forma en que los LLM se conectan a fuentes de datos externas. Puedes usar el Servidor MCP de Needle para habilitar fácilmente herramientas de búsqueda semántica en tus aplicaciones de IA, haciendo que los datos enterrados en PDFs, DOCX, XLSX y otros archivos sean accesibles instantáneamente por los LLM.

Recomendamos usar nuestro servidor MCP remoto para la mejor experiencia, sin necesidad de configuración local.

Características

  • Gestión de Documentos: Añade y organiza documentos fácilmente en el servidor.
  • Búsqueda y Recuperación: Búsqueda en lenguaje natural basada en Claude para obtener respuestas rápidas.
  • Integración Sencilla: Funciona con Claude Desktop y las colecciones de Needle.

Uso

Comandos en Claude Desktop

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

Using commands in Claude Desktop

  1. Abre Claude Desktop y conéctate al Servidor MCP de Needle.
  2. Usa comandos de texto simples para buscar, recuperar o modificar documentos.
  3. Revisa los resultados de búsqueda devueltos por Claude en una interfaz amigable.

Resultado en Needle

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

Explicación en Video de Youtube

Para un recorrido completo sobre el uso del Servidor MCP de Needle con Claude y Claude Desktop, mira este video explicativo de YouTube.

Instalación

1. Servidor MCP Remoto (Recomendado)

Configuración de Claude Desktop

Crea o actualiza tu archivo de configuración:

  • Para MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Para Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.needle.app/mcp",
        "--header",
        "Authorization:Bearer ${NEEDLE_API_KEY}"
      ],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

Configuración de Cursor

Crea o actualiza .cursor/mcp.json:

{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.needle.app/mcp",
        "--header",
        "Authorization:${NEEDLE_AUTH_HEADER}"
      ],
      "env": {
        "NEEDLE_AUTH_HEADER": "Bearer <your-needle-api-key>"
      }
    }
  }
}

Obtén tu clave API desde Configuración de Needle.

Proporcionamos dos endpoints:

  • HTTP Transmisible: https://mcp.needle.app/mcp (recomendado)
  • SSE: https://mcp.needle.app/sse

Nota: MCP ha deprecado los endpoints SSE en la última especificación, por lo que los clientes más nuevos deberían preferir el endpoint HTTP Transmisible.

2. Instalación Local

  1. Clona el repositorio:
git clone https://github.com/needle-ai/needle-mcp.git
  1. Instala UV globalmente usando Homebrew:
brew install uv
  1. Crea tu archivo de configuración:
    • Para MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Para Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuración de Claude Desktop

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

Configuración de Cursor

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}
  1. Reemplaza /path/to/needle-mcp con la ruta real de tu repositorio
  2. Añade tu clave API de Needle
  3. Reinicia Claude Desktop

Instalación mediante Smithery

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

3. Instalación con Docker

  1. Clona y construye:
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .
  1. Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "needle": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}
  1. Reinicia Claude Desktop

Ejemplos de Uso

  • "Crea una nueva colección llamada 'Documentos Técnicos'"
  • "Añade este documento a la colección, que es https://needle.app"
  • "Busca en la colección información sobre IA"
  • "Lista todas mis colecciones"

Solución de Problemas

Si no funciona:

  • Asegúrate de que uv esté instalado globalmente (si no, desinstálalo con pip uninstall uv y reinstálalo con brew install uv)
  • O encuentra la ruta de uv con which uv y reemplaza "command": "uv" con la ruta completa
  • Verifica que tu clave API de Needle sea correcta
  • Comprueba si la ruta de needle-mcp en la configuración coincide con la ubicación real de tu repositorio

Restablecer la Configuración de Claude Desktop

Si estás viendo 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. Elimina todos los datos de Claude Desktop:
  • En MacOS: rm -rf ~/Library/Application\ Support/Claude/*
  • En Windows: Elimina el contenido de %APPDATA%/Claude/
  1. Crea una configuración nueva solo con Needle:
mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json
<< 'EOL'
{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}
EOL

  1. Cierra completamente Claude Desktop (Command+Q en Mac) y relánzalo

  2. Si aún ves configuraciones antiguas:

  • Busca archivos de configuración adicionales en otras ubicaciones
  • Intenta limpiar la caché del navegador si usas la versión web
  • Verifica que el archivo de configuración se esté leyendo desde la ubicación correcta