Needle

Needle MCP 서버로 에이전트 구축하기

문서를 관리하고 Needle을 통해 Claude Desktop 애플리케이션에서 검색을 수행하기 위한 MCP(Model Context Protocol) 서버입니다.

목차

• 개요
• 기능
• 사용법
  • Claude Desktop에서의 명령어
  • Needle에서의 결과
• 설치
• 영상 설명

---

개요

Needle MCP 서버를 사용하면 다음을 할 수 있습니다:

• 빠른 검색을 위해 문서를 정리하고 저장합니다.
• Claude의 대규모 언어 모델을 통해 강력한 검색을 수행합니다.
• 향상된 문서 관리를 위해 Needle 생태계와 원활하게 통합됩니다.

MCP(Model Context Protocol)는 LLM이 외부 데이터 소스에 연결하는 방식을 표준화합니다. Needle MCP 서버를 사용하면 AI 애플리케이션에 의미론적 검색 도구를 쉽게 활성화하여 PDF, DOCX, XLSX 및 기타 파일에 묻혀 있는 데이터를 LLM이 즉시 접근할 수 있게 만들 수 있습니다.

최상의 경험을 위해 원격 MCP 서버 사용을 권장합니다 — 로컬 설정이 필요 없습니다.

---

기능

• 문서 관리: 서버에 문서를 쉽게 추가하고 정리할 수 있습니다.
• 검색 및 조회: 빠른 답변을 위한 Claude 기반 자연어 검색.
• 간편한 통합: Claude Desktop 및 Needle 컬렉션과 함께 작동합니다.

---

사용법

Claude Desktop에서의 명령어

다음은 Claude Desktop에서 서버와 상호작용하기 위해 명령어를 사용하는 방법의 예시입니다:

1. Claude Desktop을 열고 Needle MCP 서버에 연결합니다.
2. 간단한 텍스트 명령어를 사용하여 문서를 검색, 조회 또는 수정합니다.
3. 사용자 친화적인 인터페이스에서 Claude가 반환한 검색 결과를 확인합니다.

Needle에서의 결과

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

---

YouTube 영상 설명

Needle MCP 서버를 Claude 및 Claude Desktop과 함께 사용하는 전체 과정을 보려면 이 YouTube 설명 영상을 시청하세요.

---

설치

1. 원격 MCP 서버 (권장)

Claude Desktop 구성

구성 파일을 생성하거나 업데이트하세요:

• MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json
• 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>"
      }
    }
  }
}

Cursor 구성

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

Needle 설정에서 API 키를 가져오세요.

두 가지 엔드포인트를 제공합니다:

• Streamable HTTP: https://mcp.needle.app/mcp (권장)
• SSE: https://mcp.needle.app/sse

참고: MCP는 최신 사양에서 SSE 엔드포인트를 더 이상 사용하지 않으므로, 최신 클라이언트는 Streamable HTTP 엔드포인트를 사용하는 것이 좋습니다.

2. 로컬 설치

1. 저장소를 클론합니다:

git clone https://github.com/needle-ai/needle-mcp.git

2. Homebrew를 사용하여 UV를 전역적으로 설치합니다:

brew install uv

3. 구성 파일을 생성합니다:
   • MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

Claude Desktop 구성

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

Cursor 구성

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

4. /path/to/needle-mcp을(를) 실제 저장소 경로로 교체합니다
5. Needle API 키를 추가합니다
6. Claude Desktop을 다시 시작합니다

Smithery를 통한 설치

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

3. Docker 설치

1. 클론하고 빌드합니다:

git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .

2. 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>"
      }
    }
  }
}

3. Claude Desktop을 다시 시작합니다

사용 예시

• "'Technical Docs'라는 새 컬렉션을 만들어 줘"
• "이 문서를 컬렉션에 추가해 줘, 이 문서는 https://needle.app"
• "AI에 대한 정보를 컬렉션에서 검색해 줘"
• "내 모든 컬렉션을 나열해 줘"

문제 해결

작동하지 않는 경우:

• uv이(가) 전역적으로 설치되어 있는지 확인하세요 (없다면 pip uninstall uv으로 제거하고 brew install uv으로 다시 설치하세요)
• 또는 uv 경로를 which uv으로 찾아 "command": "uv"을(를) 전체 경로로 교체하세요
• Needle API 키가 올바른지 확인하세요
• 구성의 needle-mcp 경로가 실제 저장소 위치와 일치하는지 확인하세요

Claude Desktop 구성 재설정

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

1. 모든 Claude Desktop 구성 파일을 찾습니다:

find / -name "claude_desktop_config.json" 2>/dev/null

2. 모든 Claude Desktop 데이터를 제거합니다:

• MacOS의 경우: rm -rf ~/Library/Application\ Support/Claude/*
• Windows의 경우: %APPDATA%/Claude/의 내용을 삭제합니다

3. 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

4. Claude Desktop을 완전히 종료하고(Mac에서 Command+Q) 다시 실행합니다

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

• 다른 위치에 추가 구성 파일이 있는지 확인하세요
• 웹 버전을 사용하는 경우 브라우저 캐시를 지워보세요
• 구성 파일이 올바른 위치에서 읽히고 있는지 확인하세요