mcp-hkexnews
This server provides MCP tools to discover, download, parse, and search Hong Kong Stock Exchange (HKEXnews) announcements for listed companies.
List announcements:
list_hkexnews_announcements— find available announcements by stock code, date range, category, or title keyword (excludes full periodic report PDFs).Download announcements:
download_hkexnews_announcement— fetch a specific PDF (HTML fallback) using local_key, news_id, or date/title filters; idempotent.Parse announcements:
parse_hkexnews_announcement— convert downloaded PDF/HTML into page-split JSON using PyMuPDF.Keyword search:
keyword_search— full-text search within a parsed announcement with TF + position boosting, supports ANY/ALL modes and up to 5 keywords.Read pages:
get_announcement_pages— retrieve full page content by page range (default 3 pages, max 5).Diagnostic lookup:
lookup_stock_code— resolve stock code to HKEXnews stockId mapping when other tools fail, with optional cache refresh.Data persistence: Automatically caches company mappings, category tiers, and downloaded/parsed files locally under
~/.agentladle/mcp-hkexnews/data/.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-hkexnews list announcements for stock 00700"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AgentLadle MCP HKEXnews
English | 中文
🇨🇳/🇭🇰 Cloud-hosted MCP for A-share & HK listed companies (Past 3 years annual & latest interim reports). Read more | Get API Key
A MCP (Model Context Protocol) server that provides tools for discovering, downloading, parsing, and searching Hong Kong listed company announcements from HKEXnews.
It enables AI assistants (Claude, Cursor, etc.) to access HKEXnews announcement data through 6 structured tools — from discovering available announcements to keyword-searching within their pages.
Scope (v0.1): Announcements and disclosures except full periodic report PDFs (Annual / Interim / Quarterly Report and ESG Report under
t1=40000). Performance announcements (Final / Interim / Quarterly Results) are included.
Features
6 MCP tools for HKEXnews announcement data: state-driven retrieval (search directly, fallback to download/parse only when needed)
PDF document parsing using PyMuPDF — physical page extraction into page-split JSON
Local keyword search with TF + position-boost scoring, zero external search dependencies
Idempotent — already-downloaded/parsed files are automatically skipped
Zero-config install — one line to add to your MCP client, no clone or manual setup needed
Pure Python, cross-platform (Windows / macOS / Linux)
Related MCP server: sfc-data-mcp
Prerequisites
Python 3.10+ — Download Python
uv — Install uv
Note: After installing uv, restart your terminal and MCP client (e.g. Cherry Studio) to ensure the
uvcommand is recognized.
Quick Start
Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
{
"mcpServers": {
"mcp-hkexnews": {
"command": "uvx",
"args": ["agentladle-mcp-hkexnews"]
}
}
}That's it. uvx will automatically download the package and its dependencies from PyPI — no clone, no manual install, no path configuration.
Alternative: pip install
If you prefer managing the environment yourself:
pip install agentladle-mcp-hkexnewsThen configure:
{
"mcpServers": {
"mcp-hkexnews": {
"command": "agentladle-mcp-hkexnews"
}
}
}Alternative: Run from source (local development)
Clone the repository and run directly:
git clone https://github.com/agentladle/mcp-hkexnews.gitThen configure your MCP client:
{
"mcpServers": {
"mcp-hkexnews": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-hkexnews", "agentladle-mcp-hkexnews"]
}
}
}Replace /path/to/mcp-hkexnews with the actual path to the cloned repository.
Data Flow
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)Tools
# | Tool | Description |
1 |
| Discover available HKEXnews announcements for a company |
2 |
| Download announcement PDF (HTML fallback); idempotent |
3 |
| Parse PDF/HTML into page-split JSON using PyMuPDF |
4 |
| Full-text keyword search with TF relevance scoring |
5 |
| Read announcement content by page number range |
6 |
| Diagnostic: look up stock_code→stockId mapping when resolution fails |
Tool 1: list_hkexnews_announcements
List available HKEXnews announcements for a company. Use this tool ONLY when the exact date/title is unspecified by the user, or when a download attempt fails due to an ambiguous match. Excludes full periodic report PDFs (Annual / Interim / Quarterly Report and ESG Report under t1=40000).
Parameter | Type | Required | Description |
| string | ✅ | 5-digit HK stock code, e.g. |
| string | ❌ | HKEX t1/t2 code or tier name, e.g. |
| string | ❌ | Start date |
| string | ❌ | End date |
| string | ❌ | Title keyword filter |
| int | ❌ | Max announcements to return, default 10, max 50 |
Tool 2: download_hkexnews_announcement
Download a specific HKEXnews announcement from www1.hkexnews.hk. Prefer local_key from list_hkexnews_announcements when available. Idempotent.
Parameter | Type | Required | Description |
| string | ✅ | 5-digit HK stock code, e.g. |
| string | ❌ | Release date |
| string | ❌ | Title substring to disambiguate same-day announcements |
| string | ❌ | Optional category filter |
| string | ❌ | HKEXnews NEWS_ID if known |
| string | ❌ | Exact local bundle key from list results |
Tool 3: parse_hkexnews_announcement
Parse a downloaded announcement PDF/HTML into page-split JSON. Uses PyMuPDF for PDF physical-page text extraction.
Parameter | Type | Required | Description |
| string | ✅ | Bundle key returned by list/download, e.g. |
Tool 4: keyword_search
Full-text keyword search across all pages. Results ranked by TF + position-boost score.
Parameter | Type | Required | Description |
| string | ✅ | Bundle key |
| string[] | ✅ | 1–5 search keywords |
| string | ❌ |
|
| int | ❌ | Max results to return, default 5, max 50 |
Tool 5: get_announcement_pages
Read full page content by page number range.
Parameter | Type | Required | Description |
| string | ✅ | Bundle key |
| int | ✅ | Start page number (1-based) |
| int | ❌ | Number of pages to return, default 3, max 5 |
Tool 6: lookup_stock_code
Diagnostic tool: look up stock_code→stockId mapping. Use only when download_hkexnews_announcement / list_hkexnews_announcements returns Stock code not found. Bypasses the session failed-code cache.
Parameter | Type | Required | Description |
| string | ✅ | 5-digit HK stock code, e.g. |
| bool | ❌ | Force re-download of HKEX company mappings (default: |
Configuration
On first run, a default config file is created at ~/.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: 7Data Directory Structure
~/.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
└── ...File naming convention: {STOCK_CODE}_{T2_CODE}_{RELEASE_DATE}_{ID_HASH}
Example Usage
The tools are designed with an EAFP (Easier to Ask for Forgiveness than Permission) approach. AI assistants should attempt to retrieve data directly and rely on errors to trigger downloads.
Scenario A: File already exists locally (Shortest Path)
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.Scenario B: File missing (Fallback triggered)
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.Tech Stack
Component | Choice | Purpose |
MCP Framework |
| MCP server with stdio transport |
HTTP Client |
| HKEXnews API requests & file downloads |
PDF Parsing |
| PDF page text extraction; HTML fallback |
Search | Python built-in | TF + position-boost scoring |
Config |
| YAML configuration file |
Securities List |
| Parse HKEX ListOfSecurities.xlsx |
Project Structure
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 helpersLicense
MIT
Available Tools
6 toolsdownload_hkexnews_announcementA
Download an HKEXnews announcement PDF (or HTML fallback) to local storage.
<critical_rules>
Prefer local_key from list_hkexnews_announcements when available.
After success, immediately call parse_hkexnews_announcement with the returned local_key.
Full periodic report PDFs (Annual/Interim/Quarterly/ESG under t1=40000) are out of scope. </critical_rules>
Args: stock_code: 5-digit HK stock code release_date: YYYY-MM-DD (optional if local_key provided) title_keyword: Title substring to disambiguate same-day announcements category: Optional category filter news_id: HKEXnews NEWS_ID if known local_key: Exact local bundle key from list results
Inputs: stock_code (required), news_id, category, local_key, +2 more. Returns: result
get_announcement_pagesA
Retrieve full page content for a range of pages from a parsed announcement.
<critical_rules>
page_count default 3, max 5.
Prefer keyword_search for specific facts. </critical_rules>
Args: local_key: Bundle key start_page: 1-based start page page_count: Number of pages, default 3, max 5
Inputs: local_key (required), start_page (required), page_count. Returns: result
keyword_searchA
Search a parsed announcement by keywords. Results sorted by relevance.
<critical_rules>
Pass 1-5 keywords, not full sentences.
Expand synonyms when useful (e.g. ["回购", "股份回购"] or ["buyback", "repurchase"]). </critical_rules>
Args: local_key: Bundle key from list/download keywords: 1-5 search keywords match_mode: "ANY" or "ALL", default ANY max_results: Max snippets, default 5, max 50
Inputs: keywords (required), local_key (required), match_mode, max_results. Returns: result
list_hkexnews_announcementsA
List available HKEXnews announcements for a company (excludes full periodic report PDFs).
<critical_rules>
Excludes full Annual/Interim/Quarterly Report and ESG report PDFs (t1=40000).
Performance announcements (Final/Interim/Quarterly Results) are included.
limit max 50. </critical_rules>
Args: stock_code: 5-digit HK stock code, e.g. "00700" category: Optional HKEX t1/t2 code or tier name (e.g. "Inside Information", "13500") start_date: YYYY-MM-DD inclusive end_date: YYYY-MM-DD inclusive title_keyword: Optional title search keyword limit: Max announcements to return, default 10, max 50
Inputs: stock_code (required), limit, category, end_date, +2 more. Returns: result
lookup_stock_codeA
Look up HKEXnews stockId mapping for a Hong Kong stock code. Diagnostic tool.
<critical_rules>
Prefer refresh=false first (local cache). Use refresh=true only if cache is empty or the code is still missing. </critical_rules>
Args: stock_code: 5-digit HK stock code, e.g. "00700" or "700" refresh: Force re-download of company mappings (default: false)
Inputs: stock_code (required), refresh. Returns: result
parse_hkexnews_announcementA
Parse a downloaded announcement PDF/HTML into page-split JSON.
Args: local_key: Bundle key returned by list/download, e.g. "00700_13500_2026-03-15_a1b2c3d4"
Inputs: local_key (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct purpose: downloading, parsing, searching, listing, looking up stock codes, and retrieving pages. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., download_hkexnews_announcement, list_hkexnews_announcements).
6 tools is an appropriate number for the domain, covering the core workflows without being excessive or insufficient.
The tool surface covers the full lifecycle: listing, downloading, parsing, searching, and retrieving pages. No obvious gaps for the read-only nature of HKEX announcements.
Maintenance
Related MCP Connectors
MCP server for stocksense-ai documentation, generated by doc2mcp.
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
China A-share & equity research MCP server (回声投研) for market quotes, filings, financials, fund flows, concepts & sentiment.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for Japan's TDnet (Timely Disclosure network). Search and retrieve timely disclosure documents from listed companies on Japanese stock exchanges.243 PyPI6Apache 2.0
- FlicenseNot gradedqualityDmaintenanceMCP 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.-
- AlicenseNot gradedqualityCmaintenanceMCP server for analyzing SEC filings (10-K, 10-Q, 8-K) with industry-aware financial extraction and BERT-based NLP.1MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that searches and filters DART electronic disclosures for Korean companies, enabling AI agents to create investor briefing summaries.-