Skip to main content
Glama
mcp-hkexnews

mcp-hkexnews

by agentladle

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

Note: After installing uv, restart your terminal and MCP client (e.g. Cherry Studio) to ensure the uv command 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-hkexnews

Then 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.git

Then 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

list_hkexnews_announcements

Discover available HKEXnews announcements for a company

2

download_hkexnews_announcement

Download announcement PDF (HTML fallback); idempotent

3

parse_hkexnews_announcement

Parse PDF/HTML into page-split JSON using PyMuPDF

4

keyword_search

Full-text keyword search with TF relevance scoring

5

get_announcement_pages

Read announcement content by page number range

6

lookup_stock_code

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

stock_code

string

✅

5-digit HK stock code, e.g. "00700"

category

string

❌

HKEX t1/t2 code or tier name, e.g. "Inside Information", "13500", "20000". Omit to list all in-scope categories

start_date

string

❌

Start date YYYY-MM-DD

end_date

string

❌

End date YYYY-MM-DD

title_keyword

string

❌

Title keyword filter

limit

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

stock_code

string

✅

5-digit HK stock code, e.g. "00700"

release_date

string

❌

Release date YYYY-MM-DD (optional if local_key provided)

title_keyword

string

❌

Title substring to disambiguate same-day announcements

category

string

❌

Optional category filter

news_id

string

❌

HKEXnews NEWS_ID if known

local_key

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

local_key

string

✅

Bundle key returned by list/download, e.g. "00700_13500_2026-03-15_a1b2c3d4"

Tool 4: keyword_search

Full-text keyword search across all pages. Results ranked by TF + position-boost score.

Parameter

Type

Required

Description

local_key

string

✅

Bundle key

keywords

string[]

✅

1–5 search keywords

match_mode

string

❌

"ANY" (default, any keyword matches) / "ALL" (all must match)

max_results

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

local_key

string

✅

Bundle key

start_page

int

✅

Start page number (1-based)

page_count

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

stock_code

string

✅

5-digit HK stock code, e.g. "00700"

refresh

bool

❌

Force re-download of HKEX company mappings (default: false)

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: 7

Data 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 (FastMCP)

MCP server with stdio transport

HTTP Client

httpx

HKEXnews API requests & file downloads

PDF Parsing

pymupdf + beautifulsoup4

PDF page text extraction; HTML fallback

Search

Python built-in

TF + position-boost scoring

Config

pyyaml

YAML configuration file

Securities List

openpyxl

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 helpers

License

MIT

Available Tools

6 tools
download_hkexnews_announcementA

Download an HKEXnews announcement PDF (or HTML fallback) to local storage.

<critical_rules>

  1. Prefer local_key from list_hkexnews_announcements when available.

  2. After success, immediately call parse_hkexnews_announcement with the returned local_key.

  3. 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>

  1. page_count default 3, max 5.

  2. 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

list_hkexnews_announcementsA

List available HKEXnews announcements for a company (excludes full periodic report PDFs).

<critical_rules>

  1. Excludes full Annual/Interim/Quarterly Report and ESG report PDFs (t1=40000).

  2. Performance announcements (Final/Interim/Quarterly Results) are included.

  3. 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>

  1. 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

    A4.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a distinct purpose: downloading, parsing, searching, listing, looking up stock codes, and retrieving pages. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., download_hkexnews_announcement, list_hkexnews_announcements).

    Tool Count5/5

    6 tools is an appropriate number for the domain, covering the core workflows without being excessive or insufficient.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Japan's TDnet (Timely Disclosure network). Search and retrieve timely disclosure documents from listed companies on Japanese stock exchanges.
      243 PyPI
      6
      Apache 2.0
    • 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for analyzing SEC filings (10-K, 10-Q, 8-K) with industry-aware financial extraction and BERT-based NLP.
      1
      MIT