Install
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]누구에게 적합한가
MCPSurfr(이전 이름 mcp-local-rag)은 LLM을 위한 로컬 웹 검색 MCP 서버입니다. API 키가 필요 없고, 검색 결과는 사용자 자신의 머신에서 재정렬되며, 순위 매기기는 numpy 위에서 직접 돌아가는 소형 MobileBERT 모델이 담당합니다. 두 부류의 사용자에게 적합합니다. 하나는 MCP를 지원하는 클라이언트에 웹 검색 능력을 보강하면서도 검색 서비스에 가입하거나 키를 관리하고 싶지 않은 사용자이고, 다른 하나는 한 번짜리 단락 조회에서 전체 페이지 텍스트, 그리고 멀티 엔진 딥 리서치까지 단계적으로 깊어지는 워크플로가 필요한 에이전트 환경입니다.
전제 조건을 분명히 해야 합니다. 사용자 지정 MCP 서버를 지원하는 클라이언트와 uvx 명령을 실행할 수 있는 로컬 머신이 필요합니다. 공식이 제공하는 실행 방식은 uvx로 GitHub에서 서버를 끌어와 띄우는 이 한 가지뿐입니다. 공식 페이지는 호스팅 서비스나 그래픽 인터페이스 제공 여부를 설명하지 않고, 운영체제 요건과 호환 클라이언트 목록도 제시하지 않습니다. 사용 환경이 GitHub에서 코드를 내려받아 실행하는 것을 허용하지 않는다면 이 기본 경로는 사용할 수 없습니다.
3분 만에 첫 사용 시도하기
권장 기본 경로는 한 가지뿐이며, 명령과 설정은 모두 공식 설명에서 나옵니다.
전제: 로컬 머신에서 uvx를 실행할 수 있고, 클라이언트가 command/args 방식의 MCP 서버 설정을 지원해야 합니다. 첫 번째 단계, 클라이언트의 MCP 서버 설정에 공식이 제공한 조각을 넣습니다(붙여넣는 위치는 클라이언트마다 다릅니다).
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]
두 번째 단계, 설정을 저장하고 세션을 다시 불러오면 클라이언트가 이 명령으로 mcpsurfr를 띄웁니다. 최초 실행 시 GitHub에서 코드를 내려받아야 하므로 네트워크 연결이 필요하며, 소요 시간과 캐시 동작은 공식적으로 설명되어 있지 않습니다.
세 번째 단계, search 도구를 일반 검색어로 호출합니다. 공식 정의상 한 번짜리 조회로 관련 단락을 반환하며 조회 유형 작업에 속합니다. 다만 호출은 실제 웹 검색을 일으키고 재정렬 계산을 로컬에서 실행합니다. "조회 유형"은 쓰기 작업을 수행하지 않는다는 뜻일 뿐, 네트워크 요청이나 프라이버시 경계가 없다는 뜻이 아닙니다.
성공 신호: 도구가 검색어와 관련된 단락 텍스트를 반환하고, 클라이언트 도구 목록에서 search 외에 rag_search_ddgs, rag_search_google, deep_research, deep_research_ddgs, deep_research_google를 볼 수 있으면 됩니다. 서버는 스킬 리소스 skill://mcpsurfr-search/SKILL.md도 제공하지만 그 구체적인 용도는 공식 페이지에서 설명하지 않습니다.
활용 사례
사례 1: 대화에 즉답형 검색 보강하기. 상황: 클라이언트에서 새로운 진전이 있을 수 있는 주제를 논의하면서 모델이 먼저 search를 호출하게 합니다. 한 번짜리 조회로 관련 단락을 반환하고 모델이 이를 인용해 답할 수 있습니다. API 키가 필요 없으므로 새 환경에 붙을 때도 어떤 검색 서비스에도 먼저 가입할 필요가 없습니다. 관련 단락 반환까지는 확인되지만 단락 분할과 순위의 세부 방식은 공식적으로 설명되어 있지 않습니다.
사례 2: 전체 페이지 본문을 가져와 주제 정리하기. 상황: 단락으로는 부족하고 더 완전한 맥락이 필요할 때 rag_search_ddgs를 호출합니다. 공식 설명에 따르면 전체 페이지를 텍스트로 반환하며, 이것이 이 프로젝트의 원조 모드입니다. 한 번 호출에 최대 40,000자까지 반환되니 환경 변수 MCPSURFR_MAX_CHARS로 조정할 수 있습니다. 각 도구의 세부 파라미터는 공식이 항목별로 제시하지 않으므로 클라이언트가 내성적으로 확인한 도구 설명을 기준으로 삼고, deep_research 계열이 다단계 리서치를 어떻게 구성하는지는 공식 페이지에 설명이 없으니 스스로 가정하지 마십시오.
사용 경계
읽기·쓰기 성격: 여섯 도구는 모두 조회 또는 리서치 유형 능력이며, 로컬 파일 쓰기나 원격 제출 작업은 공식 페이지에 기술되어 있지 않습니다. 이는 경계 서술일 뿐 보안 결론이 아닙니다. 호출 즉시 실제 웹 검색이 일어나고 MobileBERT(numpy)로 로컬 재정렬이 수행됩니다.
자격 증명과 로컬 의존성: 공식의 핵심은 API 키가 필요 없다는 점입니다. 계정, 토큰, 로컬 데이터 파일이 필요한지는 공식 페이지에 언급이 없으니 미확인으로 다룹니다.
부작용과 확인 지점: 설치는 uvx를 통해 GitHub에서 코드를 내려받아 실행하는 행위를 포함하며, 이는 공식 설정에 내재된 동작이므로 이를 수용한 뒤에 설정에 넣으십시오. 그 외에 공식이 설명하는 다른 부작용이나 확인이 필요한 동작은 없습니다.
공식 제한과 미확인 항목: 전체 페이지 유형 도구는 한 번에 최대 40,000자를 반환하며 환경 변수 MCPSURFR_MAX_CHARS로 조정할 수 있습니다. 아직 확인되지 않은 핵심 정보로는 호환 클라이언트 목록, 검색 백엔드별 가용성과 할당량, 성능 오버헤드, 원격 배포 가능 여부가 있습니다. 이런 조건에 의존해 선택하기 전에 자신의 환경에서 먼저 검증하십시오.