MCP 服务器

Hubble MCP Server

A Python-based Model Context Protocol server that integrates with Claude Desktop, allowing users to connect to Hubble API services by configuring the server with their Hubble API key.

Tools

get_search_path

Make a request to the Path Finder API of Hubble with proper error handling. Args: keyword: str, 검색 키워드 gl: str, 지역 코드 한국 일본(kr, jp) limit: int, 검색 경로 분석 결과 최대 개수(기본값 200) Returns: dict[str, Any] | None: 검색 경로 분석 결과

get_keyword_info

키워드 정보 조회 (최대 1000개 키워드 조회 가능) 키워드 정보 조회 결과는 키워드 정보 조회 결과 형식에 따라 반환됩니다. args: req_param: KeywordParameters, 키워드 정보 조회 요청 파라미터 returns: dict[KeywordResponse, Any] | None: 키워드 정보 조회 결과 KeywordResponse 는 아래와 같은 정보를 포함합니다: ads_metrics: - competition: 경쟁도 수준 (LOW: 0-33, MEDIUM: 34-66, HIGH: 67-100) - competition_index: 구글 검색광고 경쟁도 (0-100) - cpc: 클릭당 비용 - volume_avg: 최근 3개월 월평균 검색량 - volume_total: 최근 12개월 총 검색량 - volume_trend: 3개월 전 대비 검색량 증감율 - gg_volume_avg: 구글 최근 3개월 월평균 검색량 - gg_volume_total: 구글 최근 12개월 총 검색량 - gg_volume_trend: 구글 검색량 증감율 - nv_volume_avg: 네이버 최근 3개월 월평균 검색량 - nv_volume_total: 네이버 최근 12개월 총 검색량 - nv_volume_trend: 네이버 검색량 증감율 intents: - I: Informational - N: Navigational - C: Commercial - T: Transactional monthly_volume: - month: 해당 월 - gg: 구글 검색량 - nv: 네이버 검색량 - total: 구글 + 네이버 검색량

get_graph_info

키워드 관계 정보(허블의 클러스터 파인더 결과 조회, 키워드 관계 정보 조회) args: req_param: ClusterParameters, 키워드 관계 정보 조회 요청 파라미터 returns: dict[ClusterResponse, Any] | None: 키워드 관계 정보 조회 결과 ClusterResponse 는 아래와 같은 정보를 포함합니다: nodes: 키워드(노드) 리스트 nodes_count: 키워드(노드) 수 rels: 관계 리스트 rels_count: 관계 수 closeness: 관계에서 키워드가 출현한 위치. distance: 모든 관계에서 키워드가 출현한 위치. type: PEOPLE_ALSO_SEARCH_FOR | RELATED_SEARCHES | REFINEMENTS | PEOPLE_ALSO_ASK_FOR

get_serp_info

구글 SERP API 요청

crawl_web_page

웹 페이지 크롤링 args: url_list: List[str], 크롤링할 웹 페이지 리스트 returns: dict[Any] | None: 크롤링 결과

crawl_google_suggest_extensions

키워드에 대한 구글 서제스트 확장 키워드 수집 요청 args: keyword: str, 키워드 gl: Literal['kr', 'us', 'jp'] = "kr", 국가 코드 returns: dict[Any] | None: 구글 서제스트 확장 키워드 수집 결과 키워드 확장 suggestions(common) 키워드의 suggestions(1 depth) + 1 depth 결과들의 suggestions(2 depth) suffix(나라별) 한국 (gl : kr) : 2405개 keyword + space (1 개) keyword + 한글 자음(ㄱ~ㅎ: 19 개) keyword + 한글 음절 (2350 개) keyword + 알파벳(a~z: 26 게) keyword + 숫자(0~9: 10 개) 미국 (gl : us) : 37개 keyword + space (1 개) keyword + 알파벳(a~z: 26 개) keyword + 숫자(0~9: 10 개) 일본 (gl : jp) : 2318개 keyword + space (1 개) keyword + 히라가나 (46 개) keyword + 히라가나 * 히라가나 (2116 개) keyword + 가타카나 (46 개) keyword + 일어 음절 (73 개) keyword + 알파벳(a~z: 26 개) keyword + 숫자(0~9: 10 개)

crawl_google_trends

구글 트렌드 수집 요청 최근 며칠 이내의 키워드 트렌드 추이를 0~100 사이의 값으로 표현 됩니다. (검색량은 아니고, 검색 관심도를 나타냅니다. 해당 수치는 0~100 사이의 값으로 표현 됩니다.) trends: 기간을 기준으로 차트에서 가장 높은 지점 대비 검색 관심도를 나타냅니다. 값은 검색 빈도가 가장 높은 검색어의 경우 100, 검색 빈도가 그 절반 정도인 검색어의 경우 50, 해당 검색어에 대한 데이터가 충분하지 않은 경우 0으로 나타납니다. args: keywords: List[str], 키워드 리스트 location: Literal['South Korea', 'Japan'], timeframe: Literal['now 1-H', 'now 7-d', 'today 1-m'], gl: Literal['kr', 'jp'] returns: dict[Any] | None: 구글 트렌드 수집 결과

README

hubble_mcp

⚠️ 주의

현재는 사내 VPN 환경에서만 사용 가능합니다.

간혹 API 가 실패 할수 있으니, 데이터 응답을 정상적으로 수신 했는지 확인이 필요 합니다.
(클로드가 툴 사용한 메시지를 클릭하면, API 응답 메시지 확인이 가능합니다. )

set-up-your-environment

Claude Desktop 설치
- https://claude.ai/download
uv 설치 (hubble MCP Server 는 파이썬으로 작성되었습니다.) - https://modelcontextprotocol.io/quickstart/server#set-up-your-environment
- Windows
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
  일부 보안 프로그램의 실시간 감시에서 uv 명령어가 차단될 경우, 실시간 감시를 중단 또는 해당 파일을 제외 시켜 주세요~
- MacOS/Linux
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Hubble MCP Server 다운로드
- https://github.com/ascentkorea/hubble_mcp/releases
  - zip 파일 다운로드후, 압축해제 (아래 설정파일 에서 해당 경로 필요)
  - 가장 최신 버전 사용
HUBBLE_API_KEY 발급

claude_desktop_config.json 파일 설정

클로드 데스크탑 > 파일 > 설정(Ctrl + ,) > 개발자 > 설정 편집
- json 파일 수정 이후, 클로드 데스크탑 > 파일 > 종료 를 통해서 다시 시작 필요!
맥일경우 uv 실행 파일의 절대 경로 필요, 아래 맥 샘플 참조

{
  "mcpServers": {
    "hubble": {
      "command": "uv",
      "args": [
          "--directory",
          "<Hubble MCP Server 다운로드후 zip 파일 압축 해제후 data_api.py 파일 있는 경로>",
          "run",
          "data_api.py"
      ],
      "env": {
        "HUBBLE_API_KEY": "<HUBBLE_API_KEY>"
      }
    }
  }
}

Windows 설정 파일 샘플

{
  "mcpServers": {
    "hubble": {
      "command": "uv",
      "args": [
          "--directory",
          "C:\\Users\\XXXX\\Documents\\hubble\\hubble_mcp",
          "run",
          "data_api.py"
      ],
      "env": {
        "HUBBLE_API_KEY": "xxx-xxxx-xxxx-xxx"
      }
    }
  }
}

MacOS/Linux 설정 파일 샘플

{
  "mcpServers": {
    "hubble": {
      "command": "/Users/XXX/.local/bin/uv",
      "args": [
          "--directory",
          "/Users/XXX/workspace/hubble/hubble_mcp",
          "run",
          "data_api.py"
      ],
      "env": {
        "HUBBLE_API_KEY": "xxx-xxxx-xxxx-xxx"
      }
    }
  }
}

제공 되는 tool(기능) 설명 ( https://hubble-data-api.ascentlab.io/ )

get_search_path: 검색 경로 API
get_keyword_info: 키워드에 대한 검색량(월별 검색량), 구글 SERP에 출현하는 feature type 요약, 검색 인텐트(INCT), 한국의 경우 성비/연령비
get_graph_info: 키워드간의 관계 정보
crawl_google_serp: 구글 SERP API
crawl_web_page: 일반 웹페이지 수집 API
crawl_google_suggest_extension: 구글 서제스트 API
crawl_google_trends: 구글 트렌드 API