de en es ja ko ru zh

mcp-hkexnews

Name: mcp-hkexnews
Author: agentladle

by agentladle

Overview Schema Related Servers Score Discussions

Python

Local

AgentLadle MCP HKEXnews

English | 中文

🇨🇳/🇭🇰 A주 및 홍콩 상장 기업(최근 3년 연차 보고서 및 최신 중간 보고서)용 클라우드 호스팅 MCP. 자세히 보기 | API 키 발급

HKEXnews에서 홍콩 상장 기업 공시를 검색, 다운로드, 파싱, 검색할 수 있는 도구를 제공하는 MCP(Model Context Protocol) 서버입니다.

AI 어시스턴트(Claude, Cursor 등)가 6가지 구조화된 도구를 통해 HKEXnews 공시 데이터에 접근할 수 있게 해줍니다 — 공시 검색부터 페이지 내 키워드 검색까지.

범위 (v0.1): 전체 정기 보고서 PDF(t1=40000 하위의 연차 / 중간 / 분기 보고서 및 ESG 보고서)를 제외한 공시 및 정보 공개. 실적 공시(연간 / 중간 / 분기 실적)는 포함됩니다.

주요 기능

HKEXnews 공시 데이터용 6가지 MCP 도구: 상태 기반 검색(직접 검색, 필요할 때만 다운로드/파싱으로 폴백)
PyMuPDF 기반 PDF 문서 파싱 — 물리적 페이지를 페이지별 JSON으로 추출
TF + 위치 가중치 점수를 사용한 로컬 키워드 검색, 외부 검색 의존성 없음
멱등성 — 이미 다운로드/파싱된 파일은 자동으로 건너뜀
제로 구성 설치 — MCP 클라이언트에 한 줄만 추가하면 되며, 클론이나 수동 설정 불필요
순수 Python, 크로스 플랫폼(Windows / macOS / Linux)

Related MCP server: sfc-data-mcp

사전 요구 사항

Python 3.10+ — Python 다운로드
uv — uv 설치

참고: uv 설치 후 터미널과 MCP 클라이언트(예: Cherry Studio)를 다시 시작하여 uv 명령이 인식되도록 하세요.

빠른 시작

MCP 클라이언트 구성(Claude Desktop, Cursor 등)에 추가하세요:

{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "uvx",
      "args": ["agentladle-mcp-hkexnews"]
    }
  }
}

이것으로 끝입니다. uvx가 PyPI에서 패키지와 의존성을 자동으로 다운로드합니다 — 클론, 수동 설치, 경로 구성이 필요 없습니다.

대안: pip 설치

환경을 직접 관리하고 싶다면:

pip install agentladle-mcp-hkexnews

그런 다음 구성:

{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "agentladle-mcp-hkexnews"
    }
  }
}

대안: 소스에서 실행(로컬 개발)

리포지토리를 클론하고 직접 실행:

git clone https://github.com/agentladle/mcp-hkexnews.git

그런 다음 MCP 클라이언트 구성:

{
  "mcpServers": {
    "mcp-hkexnews": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-hkexnews", "agentladle-mcp-hkexnews"]
    }
  }
}

/path/to/mcp-hkexnews를 클론한 리포지토리의 실제 경로로 바꾸세요.

데이터 흐름

HKEXnews API                      Local Files (~/.agentladle/mcp-hkexnews/data/)
──────────────                    ──────────────────────────────
activestock_sehk_e.json  ──→     companies.json               (stock_code→stockId mapping)
ListOfSecurities.xlsx      ──→         │
tierone/tiertwo JSON       ──→     tiers.json                   (headline category mapping)
                                     │
titleSearchServlet.do    ──→        pdf/{LOCAL_KEY}/            (Tool 2: primary PDF/HTML + manifest)
                                     │
PyMuPDF parsing          ──→        json/*.json                 (Tool 3: parse, page-split)
                                     │
Local TF search          ──→        search results              (Tool 4: keyword search)
Page range read          ──→        page content                (Tool 5: read pages)

도구

#	도구	설명
1	`list_hkexnews_announcements`	기업의 사용 가능한 HKEXnews 공시 검색
2	`download_hkexnews_announcement`	공시 PDF 다운로드(HTML 폴백); 멱등성
3	`parse_hkexnews_announcement`	PyMuPDF를 사용하여 PDF/HTML을 페이지별 JSON으로 파싱
4	`keyword_search`	TF 관련성 점수를 사용한 전문 키워드 검색
5	`get_announcement_pages`	페이지 번호 범위로 공시 내용 읽기
6	`lookup_stock_code`	진단: 해석 실패 시 stock_code→stockId 매핑 조회

도구 1: `list_hkexnews_announcements`

기업의 사용 가능한 HKEXnews 공시를 나열합니다. 사용자가 정확한 날짜/제목을 지정하지 않은 경우, 또는 모호한 일치로 다운로드 시도가 실패한 경우에만 이 도구를 사용하세요. 전체 정기 보고서 PDF(t1=40000 하위의 연차 / 중간 / 분기 보고서 및 ESG 보고서)는 제외됩니다.

매개변수	유형	필수	설명
`stock_code`	string	✅	5자리 홍콩 주식 코드, 예: `"00700"`
`category`	string	❌	HKEX t1/t2 코드 또는 등급 이름, 예: `"Inside Information"`, `"13500"`, `"20000"`. 생략 시 범위 내 모든 카테고리 나열
`start_date`	string	❌	시작 날짜 `YYYY-MM-DD`
`end_date`	string	❌	종료 날짜 `YYYY-MM-DD`
`title_keyword`	string	❌	제목 키워드 필터
`limit`	int	❌	반환할 최대 공시 수, 기본 10, 최대 50

도구 2: `download_hkexnews_announcement`

www1.hkexnews.hk에서 특정 HKEXnews 공시를 다운로드합니다. 가능하면 list_hkexnews_announcements의 local_key를 우선 사용하세요. 멱등성.

매개변수	유형	필수	설명
`stock_code`	string	✅	5자리 홍콩 주식 코드, 예: `"00700"`
`release_date`	string	❌	공시 날짜 `YYYY-MM-DD` (`local_key` 제공 시 선택 사항)
`title_keyword`	string	❌	같은 날짜의 공시를 구분하기 위한 제목 부분 문자열
`category`	string	❌	선택적 카테고리 필터
`news_id`	string	❌	알고 있는 경우 HKEXnews NEWS_ID
`local_key`	string	❌	목록 결과의 정확한 로컬 번들 키

도구 3: `parse_hkexnews_announcement`

다운로드한 공시 PDF/HTML을 페이지별 JSON으로 파싱합니다. PDF 물리적 페이지 텍스트 추출에 PyMuPDF를 사용합니다.

매개변수	유형	필수	설명
`local_key`	string	✅	목록/다운로드에서 반환된 번들 키, 예: `"00700_13500_2026-03-15_a1b2c3d4"`

도구 4: `keyword_search`

모든 페이지에 대한 전문 키워드 검색. 결과는 TF + 위치 가중치 점수로 순위가 매겨집니다.

매개변수	유형	필수	설명
`local_key`	string	✅	번들 키
`keywords`	string[]	✅	1–5개 검색 키워드
`match_mode`	string	❌	`"ANY"` (기본값, 키워드 중 하나라도 일치) / `"ALL"` (모두 일치해야 함)
`max_results`	int	❌	반환할 최대 결과 수, 기본 5, 최대 50

도구 5: `get_announcement_pages`

페이지 번호 범위로 전체 페이지 내용을 읽습니다.

매개변수	유형	필수	설명
`local_key`	string	✅	번들 키
`start_page`	int	✅	시작 페이지 번호(1부터 시작)
`page_count`	int	❌	반환할 페이지 수, 기본 3, 최대 5

도구 6: `lookup_stock_code`

진단 도구: stock_code→stockId 매핑을 조회합니다. download_hkexnews_announcement / list_hkexnews_announcements가 Stock code not found를 반환할 때만 사용하세요. 세션의 실패 코드 캐시를 우회합니다.

매개변수	유형	필수	설명
`stock_code`	string	✅	5자리 홍콩 주식 코드, 예: `"00700"`
`refresh`	bool	❌	HKEX 기업 매핑 강제 재다운로드 (기본값: `false`)

구성

첫 실행 시 ~/.agentladle/mcp-hkexnews/config.yaml에 기본 구성 파일이 생성됩니다:

paths:
  data_dir: "~/.agentladle/mcp-hkexnews/data"
  pdf_dir: "~/.agentladle/mcp-hkexnews/data/pdf"
  json_dir: "~/.agentladle/mcp-hkexnews/data/json"

download:
  delay_between_requests: 0.3
  min_file_size: 500
  list_row_range: 100
  list_max_pages: 5

company:
  cache_ttl_days: 7

tiers:
  cache_ttl_days: 7

데이터 디렉터리 구조

~/.agentladle/mcp-hkexnews/
├── config.yaml                        # Configuration (auto-created)
└── data/
    ├── companies.json                 # stock_code→stockId mapping (auto-downloaded & cached)
    ├── tiers.json                     # HKEX headline category mapping (auto-downloaded & cached)
    ├── pdf/                           # Downloaded announcement bundles
    │   ├── 00700_13500_2026-03-15_a1b2c3d4/
    │   │   ├── primary.pdf
    │   │   └── manifest.json
    │   └── ...
    └── json/                          # Parsed page-split JSON
        ├── 00700_13500_2026-03-15_a1b2c3d4.json
        └── ...

파일 이름 규칙: {STOCK_CODE}_{T2_CODE}_{RELEASE_DATE}_{ID_HASH}

사용 예시

도구는 EAFP(Easier to Ask for Forgiveness than Permission) 방식으로 설계되었습니다. AI 어시스턴트는 데이터를 직접 검색하고 오류에 의존하여 다운로드를 트리거해야 합니다.

시나리오 A: 파일이 이미 로컬에 존재함 (최단 경로)

User: "Search 00700 inside information for buyback"

1. keyword_search(local_key="00700_50100_2026-07-09_a1b2c3d4", keywords=["buyback", "repurchase"])
   → Returns page snippets matching the keywords immediately.

시나리오 B: 파일 없음 (폴백 트리거)

User: "What did Tencent announce in its latest inside information?"

1. list_hkexnews_announcements(stock_code="00700", category="Inside Information", limit=3)
   → Returns local_key / release_date / title.

2. keyword_search(local_key="...", keywords=["inside information"])
   → Error: File not found.

3. download_hkexnews_announcement(stock_code="00700", local_key="...")
   → Downloads PDF to ~/.agentladle/mcp-hkexnews/data/pdf/

4. parse_hkexnews_announcement(local_key="...")
   → Parses into JSON.

5. keyword_search(local_key="...", keywords=["inside information"])
   → Retries search and returns data.

기술 스택

구성 요소	선택	목적
MCP 프레임워크	`mcp` (FastMCP)	stdio 전송을 사용하는 MCP 서버
HTTP 클라이언트	`httpx`	HKEXnews API 요청 및 파일 다운로드
PDF 파싱	`pymupdf` + `beautifulsoup4`	PDF 페이지 텍스트 추출; HTML 폴백
검색	Python 내장	TF + 위치 가중치 점수
구성	`pyyaml`	YAML 구성 파일
증권 목록	`openpyxl`	HKEX ListOfSecurities.xlsx 파싱

프로젝트 구조

src/mcp_hkexnews/
├── __init__.py
├── server.py                 # MCP Server entry point
├── config.py                 # Config loading (~/.agentladle/mcp-hkexnews/config.yaml, singleton cached)
├── models.py                 # Data models
├── categories.py             # Announcement category blacklist
├── response.py               # Unified JSON responses
├── instances.py              # Service singletons
├── tools/
│   ├── list_announcements.py # Tool 1: list_hkexnews_announcements
│   ├── download.py           # Tool 2: download_hkexnews_announcement
│   ├── parse.py              # Tool 3: parse_hkexnews_announcement
│   ├── search.py             # Tool 4: keyword_search
│   ├── page.py               # Tool 5: get_announcement_pages
│   └── lookup.py             # Tool 6: lookup_stock_code
└── services/
    ├── company.py            # HKEX activestock + ListOfSecurities + stock_code→stockId
    ├── tiers.py              # HKEX tierone/tiertwo category cache
    ├── downloader.py         # HKEXnews titleSearch + PDF download
    ├── parser.py             # PDF/HTML→JSON parsing (PyMuPDF)
    ├── searcher.py           # Local JSON search + TF scoring
    └── keys.py               # local_key helpers

라이선스

MIT

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

tdnet-disclosure-mcp
Finance Search
ajtgjmdjp
A
license
Not graded
quality
A
maintenance
MCP server for Japan's TDnet (Timely Disclosure network). Search and retrieve timely disclosure documents from listed companies on Japanese stock exchanges.
Updated 4 days ago (2026-08-23 08:17 UTC)
5
Apache 2.0
sfc-data-mcp
Finance Research & Data
yangxinagfeng123
F
license
Not graded
quality
D
maintenance
MCP server that wraps SFC financial data API into 32 tools for comprehensive A-share market data, including real-time quotes, rankings, limit-up statistics, news, themes, financials, charts, research reports, and watchlists.
Updated 3 months ago (2026-05-26 08:03 UTC)
SEC-MCP
Finance AI & Machine Learning
Aomala
A
license
Not graded
quality
B
maintenance
MCP server for analyzing SEC filings (10-K, 10-Q, 8-K) with industry-aware financial extraction and BERT-based NLP.
Updated 11 days ago (2026-08-17 04:47 UTC)
1
MIT
DART 공시 브리핑 MCP 서버
Finance Government Data Search
iiacjay
F
license
Not graded
quality
C
maintenance
MCP server that searches and filters DART electronic disclosures for Korean companies, enabling AI agents to create investor briefing summaries.
Updated a month ago (2026-07-14 16:20 UTC)

View all related MCP servers

Related MCP Connectors

Octoparse MCP Server
Official Octoparse MCP server for template discovery, cloud tasks, and structured data export.
better-notion-mcp
Markdown-first MCP server for Notion API with 8 composite tools and 39 actions.
HasData
All HasData scraping tools in one MCP server: Google, TikTok, Instagram, maps, e-commerce and more.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/agentladle/mcp-hkexnews'

If you have feedback or need assistance with the MCP directory API, please join our Discord server