What can you do with this server?

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

How do I use mcp-hkexnews?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

de en es ja ko ru zh

mcp-hkexnews

by agentladle

Overview Schema Related Servers Score Discussions

Python

Local

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

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

AgentLadle MCP HKEXnews

Features

Prerequisites

Quick Start

Alternative: pip install

Alternative: Run from source (local development)

Data Flow

Tools

Tool 1: list_hkexnews_announcements

Tool 2: download_hkexnews_announcement

Tool 3: parse_hkexnews_announcement

Tool 4: keyword_search

Tool 5: get_announcement_pages

Tool 6: lookup_stock_code

Configuration

Data Directory Structure

Example Usage

Tech Stack

Project Structure

License

Maintenance

Resources

Looking for Admin?

Tools

Related MCP Servers

tdnet-disclosure-mcp

sfc-data-mcp

SEC-MCP

DART 공시 브리핑 MCP 서버

Related MCP Connectors

Latest Blog Posts

MCP directory API

Tool 1: `list_hkexnews_announcements`

Tool 2: `download_hkexnews_announcement`

Tool 3: `parse_hkexnews_announcement`

Tool 4: `keyword_search`

Tool 5: `get_announcement_pages`

Tool 6: `lookup_stock_code`