Brave Search MCP는 Brave Search API를 Model Context Protocol(MCP) 스펙으로 감싼 stdio 서버다. Claude Code 같은 호환 에이전트가 별도의 SDK 호출 없이 웹 검색과 지역 검색을 네이티브 도구처럼 호출하도록 만든다.

2026. 5. 11. 10:15ㆍAI/Claude ai

<!doctype html>

MCP SERVER · USER SCOPE · CONNECTED

웹 검색을
에이전트의 도구로
그대로 연결한다.

Brave Search MCP는 Brave Search API를 Model Context Protocol(MCP) 스펙으로 감싼 stdio 서버다. Claude Code 같은 호환 에이전트가 별도의 SDK 호출 없이 웹 검색과 지역 검색을 네이티브 도구처럼 호출하도록 만든다.

Serverbrave-search

Status✓ Connected

ScopeUser

Transportstdio

Quota2,000 req / mo · Free

Installed2026-05-11

— 01

정의WHAT THE SERVER IS

Brave Search MCP는 npm 패키지 @modelcontextprotocol/server-brave-search 로 배포되며, stdio 표준 입출력을 통해 MCP 호스트(Claude Code 등)와 통신하는 경량 서버 프로세스다. 내부적으로는 Brave Search API 의 두 엔드포인트 (/web/search, /local/search)를 호출해 결과를 MCP 응답 형식으로 변환한다.

구조 한눈에 보기

01 / Host

Claude Code

도구 호출 의사결정. stdio로 자식 프로세스를 spawn 한다.

02 / Server

server-brave-search

npx로 실행되는 Node 프로세스. MCP 프로토콜과 Brave API를 중개.

03 / API

Brave Search API

실제 검색을 수행. 개인 정보 보호 인덱스 기반.

왜 Brave 인가

독자 인덱스 — Google/Bing 재포장이 아닌 Brave가 직접 크롤한 결과
추적 없는 검색 — 사용자 프로파일링 없음, 결과 편향 최소화
관대한 무료 한도 — 월 2,000 쿼리를 신용카드 등록 후 즉시 사용
2025 이후 신규 발급 가능 — Google Custom Search JSON API가 신규 사용자에게 닫힌 시점에 실질적 대안

— 02

사용 방법HOW TO INVOKE

설치되면 자동으로 두 개의 도구가 도구 목록에 노출된다. 사용자는 자연어로 검색을 요청하면 되고, 에이전트가 적절한 도구를 선택해 호출한다.

제공 도구

도구	용도	주요 파라미터
brave_web_search	일반 웹 검색. 뉴스, 기사, 기술 문서, 사실 확인.	`query`(필수) · `count`(1–20, 기본 10) · `offset`(0–9)
brave_local_search	지역 비즈니스/장소. 영업시간·평점·전화번호 포함. 결과 없으면 웹 검색으로 자동 폴백.	`query`(필수) · `count`(1–20, 기본 5)

자연어 호출 예시

# 채팅창에 한국어로 요청하면 알아서 도구 선택
"Next.js 15 신기능 검색해줘"
"강남역 근처 파스타집 알려줘"
"오늘 비트코인 가격 검색"
"FastAPI 0.115 변경사항 확인해줘"

제약사항

쿼리 길이 — 최대 400자 / 50단어
웹 검색 페이지네이션 — offset 0–9 범위 (즉 최대 200개 결과까지 도달 가능)
지역 검색 폴백 — 결과 0건일 때 자동으로 웹 검색으로 전환
Rate limit — Free 플랜은 초당 1쿼리(QPS=1) 제한, 동시 요청 시 일부 실패 가능

응답 형식

각 결과 항목은 title, description, url을 포함한다. 모델은 이 텍스트를 받아 요약·인용·후속 검색을 결정한다. 본문 전체 스크랩이 필요하면 별도의 fetcher(예: Tavily Extract)를 조합해 사용한다.

— 03

설치 내역WHAT WAS DEPLOYED

현재 호스트(C:\Users\sangk)에 user 스코프로 설치되어 있다. user 스코프이므로 이 PC의 모든 Claude Code 프로젝트에서 동일한 설정이 자동 적용된다.

실행된 설치 명령

claude mcp add brave-search -s user \
  -e BRAVE_API_KEY=BSAPrg60Bo4Eg8MGYy9V1JjRrb6feSq \
  -e "APPDATA=C:\Users\sangk\AppData\Roaming\\" \
  -- npx.cmd -y @modelcontextprotocol/server-brave-search

⚑ Windows 주의점

기본적으로 command: "npx" 로 등록하면 Git Bash 환경에서 /c 가 C:/ 로 자동 경로 변환되어 실행이 실패한다. 반드시 npx.cmd 를 명시해 PATH 셸 매핑을 우회한다.

등록된 설정 (요약)

// C:\Users\sangk\.claude.json (user-scope mcpServers)
{
  "brave-search": {
    "type": "stdio",
    "command": "npx.cmd",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "BSAP**********************",
      "APPDATA": "C:\\Users\\sangk\\AppData\\Roaming\\"
    }
  }
}

경로	역할
C:\Users\sangk\.claude.json	user 스코프 MCP 등록부 (정식 설정)
C:\projects\claude\mcp\brave.mcp.txt	원본 API 키 정의 (가져오기 입력)
C:\projects\claude\mcp\mcp-servers.json	동작 중 MCP의 백업 사본
C:\projects\claude\mcp\brave-search-mcp.html	본 운영 노트

상태 확인 명령

# 단일 서버 상태
claude mcp get brave-search

# 전체 MCP 헬스체크
claude mcp list

# 제거가 필요할 때
claude mcp remove brave-search -s user

— 04

주의사항OPERATIONAL CAUTIONS

⚠ 보안 — API 키 평문 노출

.claude.json, brave.mcp.txt, mcp-servers.json 세 파일 모두에 BRAVE_API_KEY가 평문으로 저장돼 있다.

git 저장소에 들어가면 즉시 키가 유출되므로 다음 조치를 권장한다 — .gitignore 에 *.mcp.txt, mcp-servers.json 추가 · 평문 백업 파일은 ~/.secrets/ 같은 비공개 위치로 이동 또는 삭제. 유출 의심 시 Brave 대시보드에서 즉시 키 회전(rotate).

운영 한도

플랜	월 한도	QPS	비용
Free	2,000	1	$0 · 카드 등록 필요
Base	~ 20M	20	$3 / 1,000 쿼리
Pro	~ 20M	50	$5 / 1,000 쿼리 (스키마 확장)

알아두면 좋을 함정

최신성 한계 — 인덱스는 거의 실시간이지만 분 단위 속보엔 부정확할 수 있다. 시세·재해 속보엔 1차 출처 확인 필요.
지역 검색 정확도 — 한국어 로컬 쿼리는 미국·유럽 대비 결과 풍부도가 떨어지는 경우가 있다. 부족하면 brave_web_search 로 우회.
QPS 1 제약 — 병렬 에이전트가 동시에 호출하면 일부가 즉시 실패한다. 다중 에이전트 워크플로에선 직렬 호출 또는 캐싱이 필수.
결과 본문 미제공 — 결과 항목은 메타데이터(title/desc/url) 위주. 본문이 필요하면 페이지 fetcher와 조합하라.
NPX 캐시 부풀음 — -y 옵션으로 매번 자동 설치 → npm 캐시가 누적된다. 디스크가 빠듯하면 정기적으로 npm cache clean --force.
네트워크 차단 환경 — 사내 프록시·방화벽 환경에선 HTTPS_PROXY env를 추가 등록해야 동작한다.

롤백·재설치 시나리오

# 1) 제거
claude mcp remove brave-search -s user

# 2) 캐시·잔여 제거가 필요하면
npm cache clean --force

# 3) 재설치 (키만 새로 발급해서 교체)
claude mcp add brave-search -s user \
  -e BRAVE_API_KEY=<NEW_KEY> \
  -- npx.cmd -y @modelcontextprotocol/server-brave-search

# 4) 정상 연결 확인
claude mcp get brave-search   # → Status: ✓ Connected

체크리스트

설치 직후 — claude mcp get brave-search 로 ✓ Connected 확인
1회 검색 테스트 — 한국어 일반 질의로 결과 3건 이상 회수 검증
키 보호 — 평문 파일들의 git 추적 차단 또는 비공개 폴더로 이동
월말 — Brave 대시보드에서 사용량 점검 (2,000 한도 도달 여부)
변경 시 — 키 회전 후 .claude.json 의 env.BRAVE_API_KEY 갱신, 호스트 재시작

'AI > Claude ai' 카테고리의 다른 글

Tavily MCP · 운영 노트 (0)	2026.05.11
Playwright MCP(Model Context Protocol) (0)	2025.07.03

whylite

whylite

태그

최근글

댓글

공지사항

아카이브

웹 검색을
에이전트의 도구로
그대로 연결한다.

정의WHAT THE SERVER IS

구조 한눈에 보기

왜 Brave 인가

사용 방법HOW TO INVOKE

제공 도구

자연어 호출 예시

제약사항

응답 형식

설치 내역WHAT WAS DEPLOYED

실행된 설치 명령

등록된 설정 (요약)

관련 파일

상태 확인 명령

주의사항OPERATIONAL CAUTIONS

운영 한도

알아두면 좋을 함정

롤백·재설치 시나리오

체크리스트

'AI > Claude ai' 카테고리의 다른 글

관련글

티스토리툴바

whylite

태그

최근글

댓글

공지사항

아카이브

웹 검색을에이전트의 도구로그대로 연결한다.

정의WHAT THE SERVER IS

구조 한눈에 보기

왜 Brave 인가

사용 방법HOW TO INVOKE

제공 도구

자연어 호출 예시

제약사항

응답 형식

설치 내역WHAT WAS DEPLOYED

실행된 설치 명령

등록된 설정 (요약)

관련 파일

상태 확인 명령

주의사항OPERATIONAL CAUTIONS

운영 한도

알아두면 좋을 함정

롤백·재설치 시나리오

체크리스트

'AI > Claude ai' 카테고리의 다른 글

관련글

티스토리툴바

웹 검색을
에이전트의 도구로
그대로 연결한다.