Needle MCP Server

oficial

RAG pronto para produção para pesquisar e recuperar dados dos seus próprios documentos.

GitHub
99

Documentação

Crie Agentes com o Servidor Needle MCP

smithery badge

Screenshot of Feature - Claude

Servidor MCP (Model Context Protocol) para gerenciar documentos e realizar buscas usando o Needle através do Aplicativo Desktop do Claude.

Needle Server MCP server

Índice

Visão Geral

O Needle MCP Server permite que você:

  • Organize e armazene documentos para recuperação rápida.
  • Realize buscas poderosas através do modelo de linguagem do Claude.
  • Integre-se perfeitamente ao ecossistema Needle para gerenciamento avançado de documentos.

O MCP (Model Context Protocol) padroniza a forma como os LLMs se conectam a fontes de dados externas. Você pode usar o Needle MCP Server para habilitar facilmente ferramentas de busca semântica em suas aplicações de IA, tornando dados enterrados em PDFs, DOCX, XLSX e outros arquivos instantaneamente acessíveis pelos LLMs.

Recomendamos usar nosso servidor MCP remoto para a melhor experiência - sem necessidade de configuração local.

Funcionalidades

  • Gerenciamento de Documentos: Adicione e organize documentos facilmente no servidor.
  • Busca e Recuperação: Busca em linguagem natural baseada no Claude para respostas rápidas.
  • Integração Fácil: Funciona com o Claude Desktop e coleções do Needle.

Uso

Comandos no Claude Desktop

Abaixo está um exemplo de como os comandos podem ser usados no Claude Desktop para interagir com o servidor:

Using commands in Claude Desktop

  1. Abra o Claude Desktop e conecte-se ao Needle MCP Server.
  2. Use comandos de texto simples para buscar, recuperar ou modificar documentos.
  3. Revise os resultados da busca retornados pelo Claude em uma interface amigável.

Resultado no Needle

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

Explicação em Vídeo no YouTube

Para um passo a passo completo sobre como usar o Needle MCP Server com o Claude e o Claude Desktop, assista a este vídeo explicativo no YouTube.

Instalação

1. Servidor MCP Remoto (Recomendado)

Configuração do Claude Desktop

Crie ou atualize seu arquivo de configuração:

  • 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>"
      }
    }
  }
}

Configuração do Cursor

Crie ou atualize .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>"
      }
    }
  }
}

Obtenha sua chave de API nas Configurações do Needle.

Fornecemos dois endpoints:

  • HTTP Transmissível: https://mcp.needle.app/mcp (recomendado)
  • SSE: https://mcp.needle.app/sse

Nota: O MCP descontinuou os endpoints SSE na especificação mais recente, então clientes mais novos devem preferir o endpoint HTTP Transmissível.

2. Instalação Local

  1. Clone o repositório:
git clone https://github.com/needle-ai/needle-mcp.git
  1. Instale o UV globalmente usando o Homebrew:
brew install uv
  1. Crie seu arquivo de configuração:
    • Para MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Para Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuração do Claude Desktop

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

Configuração do Cursor

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}
  1. Substitua /path/to/needle-mcp pelo caminho real do seu repositório
  2. Adicione sua chave de API do Needle
  3. Reinicie o Claude Desktop

Instalando via Smithery

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

3. Instalação com Docker

  1. Clone e construa:
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .
  1. Adicione à sua configuração do 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. Reinicie o Claude Desktop

Exemplos de Uso

  • "Crie uma nova coleção chamada 'Documentos Técnicos'"
  • "Adicione este documento à coleção, que é https://needle.app"
  • "Busque na coleção informações sobre IA"
  • "Liste todas as minhas coleções"

Solução de Problemas

Se não estiver funcionando:

  • Certifique-se de que o uv está instalado globalmente (se não, desinstale com pip uninstall uv e reinstale com brew install uv)
  • Ou encontre o caminho do uv com which uv e substitua "command": "uv" pelo caminho completo
  • Verifique se sua chave de API do Needle está correta
  • Confira se o caminho needle-mcp na configuração corresponde à localização real do seu repositório

Redefinir a Configuração do Claude Desktop

Se você estiver vendo configurações antigas ou a integração não estiver funcionando:

  1. Encontre todos os arquivos de configuração do Claude Desktop:
find / -name "claude_desktop_config.json" 2>/dev/null
  1. Remova todos os dados do Claude Desktop:
  • No MacOS: rm -rf ~/Library/Application\ Support/Claude/*
  • No Windows: Exclua o conteúdo de %APPDATA%/Claude/
  1. Crie uma configuração nova apenas com o 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. Feche completamente o Claude Desktop (Command+Q no Mac) e reinicie-o

  2. Se ainda vir configurações antigas:

  • Verifique se há arquivos de configuração adicionais em outros locais
  • Tente limpar o cache do navegador se estiver usando a versão web
  • Verifique se o arquivo de configuração está sendo lido do local correto