# HKEx Filings

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/simonplmak-cloud/hkex-filing-scraper  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hkex-filings

## Description
Live HKEx (Hong Kong Stock Exchange) regulatory filings for AI agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "hkex-filings": {
    "command": "npx",
    "args": ["-y","hkex-filings"]
  }
}
```

## Documentation & README

# HKEx Filing Scraper

![HKEx Filing Scraper — one scraper, many databases](https://raw.githubusercontent.com/simonplmak-cloud/hkex-filing-scraper/main/docs/social_preview.png)

[![CI](https://github.com/simonplmak-cloud/hkex-filing-scraper/actions/workflows/ci.yml/badge.svg)](https://github.com/simonplmak-cloud/hkex-filing-scraper/actions/workflows/ci.yml)
[![GitHub Release](https://img.shields.io/github/v/release/simonplmak-cloud/hkex-filing-scraper?color=green)](https://github.com/simonplmak-cloud/hkex-filing-scraper/releases)
[![PyPI](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fhkex-filing-scraper%2Fjson&query=%24.info.version&label=PyPI&color=blue)](https://pypi.org/project/hkex-filing-scraper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-server-blueviolet)](https://hkex-listco-updates.ascent-partners.com/ai-agents/)
[![mcp-hkex-filing MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper/badges/score.svg)](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper)
[![Docs](https://img.shields.io/badge/docs-hkex--listco--updates.ascent--partners.com-blue)](https://hkex-listco-updates.ascent-partners.com/)
[![Ruff](https://img.shields.io/badge/lint-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?logo=postgresql&logoColor=white)](https://www.postgresql.org)
[![MySQL](https://img.shields.io/badge/MySQL-4479A1?logo=mysql&logoColor=white)](https://www.mysql.com)
[![SQLite](https://img.shields.io/badge/SQLite-003B57?logo=sqlite&logoColor=white)](https://sqlite.org)
[![MongoDB](https://img.shields.io/badge/MongoDB-47A248?logo=mongodb&logoColor=white)](https://www.mongodb.com)
[![Neo4j](https://img.shields.io/badge/Neo4j-4581C3?logo=neo4j&logoColor=white)](https://neo4j.com)
[![ClickHouse](https://img.shields.io/badge/ClickHouse-FFCC01?logo=clickhouse&logoColor=black)](https://clickhouse.com)
[![DuckDB](https://img.shields.io/badge/DuckDB-FFF000?logo=duckdb&logoColor=black)](https://duckdb.org)
[![SurrealDB](https://img.shields.io/badge/SurrealDB-FF00A0?logo=surrealdb&logoColor=white)](https://surrealdb.com)

An open-source Python tool that scrapes 25+ years of Hong Kong Stock Exchange (HKEx)
regulatory filings and ingests them into **any combination of nine databases** — with
full-text and table extraction, chunk-level coverage, optional graph linking, and a
**read-only MCP server** so AI agents can query the corpus or the live site.

<!-- mcp-name: io.github.simonplmak-cloud/hkex-filings -->

It speaks the undocumented HKEx JSON API directly, which is faster and more resilient than
driving a browser.

## Vendors & integrations

**Databases** — nine first-class destinations, in documented popularity order (see the
[support matrix](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/README.md)):

- [PostgreSQL](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/postgresql.md) — production-grade open-source relational
- [MySQL](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/mysql.md) / [MariaDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/mysql.md) — GPL relational servers, one driver
- [SQLite](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/sqlite.md) — zero-server file database, no install needed
- [MongoDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/mongodb.md) — document database
- [Neo4j](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/neo4j.md) — property-graph database
- [ClickHouse](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/clickhouse.md) — columnar analytics engine
- [DuckDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/duckdb.md) — in-process analytical engine
- [SurrealDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/surrealdb.md) — multi-model graph + document database

**AI clients** — any MCP-capable agent; ready-made configuration for
[Claude, ChatGPT, Cursor, VS Code/Copilot, Gemini CLI, opencode, Manus, and Perplexity](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/ai-agents.md).

**Available on** — [PyPI](https://pypi.org/project/hkex-filing-scraper/) ·
[Glama](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper) ·
[MCP Registry](https://registry.modelcontextprotocol.io/) ·
[hosted gateway](https://hkex-listco-updates.ascent-partners.com/api/mcp).

## Two ways to use it

| | **Hosted MCP gateway** | **Local pipeline** |
| --- | --- | --- |
| What | A public endpoint you point an AI agent at | The `hkex-scraper` CLI |
| Setup | None — paste a URL | `pip install` + one environment variable |
| Data | Live from HKEx, nothing stored | Stored in your database(s) |
| Docs | [Live MCP gateway](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/live-mcp.md) · [AI agent support](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/ai-agents.md) | [Getting started](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/getting-started.md) |

![Example: install, scrape filings into SQLite, then query the hosted MCP gateway from an AI agent](https://raw.githubusercontent.com/simonplmak-cloud/hkex-filing-scraper/main/docs/assets/demo.svg)

## Use the hosted MCP gateway

POST, Streamable HTTP, **no API key**:

```text
https://hkex-listco-updates.ascent-partners.com/api/mcp
```

Four read-only tools: `get_server_info`, `search_filings` (a window of at most 31 days, with
optional stock-code, title, document-type, category, and stock-name filters),
`list_filing_facets` (browse what a window contains), and `get_filing` (downloads one
document and extracts its text and tables).

![Two ways to reach HKEx filings from an AI agent: the hosted MCP gateway or the local stdio server](https://raw.githubusercontent.com/simonplmak-cloud/hkex-filing-scraper/main/docs/assets/mcp.png)

Point a client at it — for example opencode:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hkex-live": {
      "type": "remote",
      "url": "https://hkex-listco-updates.ascent-partners.com/api/mcp"
    }
  }
}
```

Then ask:

```text
Use hkex-live to list the filings published between 2026-09-01 and 2026-09-18,
then summarise the interim report.
```

Ready-made configuration for Claude, ChatGPT, Cursor, VS Code/Copilot, Gemini CLI, opencode,
Manus, and Perplexity is in [AI agent support](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/ai-agents.md) — and for a stored corpus,
the [stdio MCP server](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/mcp.md) exposes a wider tool catalog and is published on
[Glama](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper). The gateway is listed
in the [official MCP Registry](https://registry.modelcontextprotocol.io/) as
`io.github.simonplmak-cloud/hkex-filings`.

> **Featured on Glama** — the read-only [stdio MCP server](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/mcp.md) is also published on
> [Glama](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper), where Glama scans the
> built server and scores tool-definition quality (currently 4.7/5).
>
> [![mcp-hkex-filing MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper/badges/card.svg)](https://glama.ai/mcp/servers/simonplmak-cloud/hkex-filing-scraper)

## Quick start (local)

```bash
pip install hkex-filing-scraper        # core; SQLite needs no server
pip install "hkex-filing-scraper[all]" # Excel + dotenv + every driver + the MCP server
cp .env.example .env                   # then set DATABASE_TARGET (below)
hkex-scraper --metadata-only --limit 100
```

Optional extras: `excel`, `postgres`, `mysql`, `duckdb`, `mongodb`, `clickhouse`, `neo4j`,
`mcp`, `pdf`, `all`, `dev`.

`DATABASE_TARGET` is an ordered, comma-separated list of sink ids; the order decides which
sink serves reads. To start with no server:

```ini
DATABASE_TARGET=sqlite
SQLITE_PATH=hkex.db
```

`hkex-scraper` runs the full pipeline (metadata + documents + graph); `hkex-scraper
--full-history` covers everything since April 1999. The schema is created automatically.
Full install options and per-sink settings are in [Getting started](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/getting-started.md).

## Database support

Every sink is a first-class destination; rows are in documented popularity order. The full
matrix — licenses, capability differences, per-engine notes — is in
[Database sinks](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/README.md).

| Sink | Model | License | Extra | Idempotent upsert |
| ---- | ----- | ------- | ----- | ----------------- |
| `postgres` | relational | PostgreSQL License | `postgres` | `ON CONFLICT DO UPDATE` |
| `mysql` / `mariadb` | relational | GPLv2 | `mysql` | `ON DUPLICATE KEY UPDATE` |
| `sqlite` | relational | Public domain | — | `ON CONFLICT DO UPDATE` |
| `mongodb` | document | SSPL¹ | `mongodb` | `update_one(upsert=True)` |
| `neo4j` | graph | GPLv3 (Community) | `neo4j` | `MERGE` |
| `clickhouse` | columnar | Apache-2.0 | `clickhouse` | `ReplacingMergeTree` + read-merge |
| `duckdb` | relational | MIT | `duckdb` | `ON CONFLICT DO UPDATE` |
| `surrealdb` | graph + document | BSL 1.1¹ | — | `UPSERT` / `RELATE` |

¹ Source-available, not OSI-approved — labeled exceptions per
[ADR 0003](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/adr/0003-sink-support-policy.md).

Valid sink ids, in documented order: `postgres`, `mysql`, `sqlite`, `mongodb`, `mariadb`, `neo4j`, `clickhouse`, `duckdb`, `surrealdb`. Set one variable and the same run feeds every sink:

```ini
# Order sets read precedence.
DATABASE_TARGET=postgres,sqlite
POSTGRES_DSN=postgresql://user:password@localhost:5432/hkex
SQLITE_PATH=hkex.db
```

## How it works

```mermaid
flowchart LR
    A[HKEx JSON API] --> B[Phase 1: metadata]
    B --> C[Canonical record]
    C --> D{DATABASE_TARGET}
    D --> E[(PostgreSQL)]
    D --> F[(MySQL / MariaDB)]
    D --> G[(SQLite)]
    D --> H[(MongoDB)]
    D --> I[(Neo4j)]
    D --> J[(ClickHouse)]
    D --> K[(DuckDB)]
    D --> L[(SurrealDB)]
    B --> M[Graph linking]
    M --> D
    B --> N[Phase 2: download and extract]
    N --> C
```

- **Phase 1** scrapes filing metadata through a JSF session, splitting the range into monthly
  chunks and deduplicating on a 16-character MD5 `filingId`.
- **Phase 2** downloads each filing's PDF/HTML/Excel document, extracts text and tables to
  Markdown, and writes the payload.
- **Graph linking** (optional) writes `has_filing` and `references_filing` edges when
  `COMPANY_TABLE` is set.
- **Failure isolation** — a failure on one sink is logged and counted but never blocks
  another; the run exits non-zero if any configured sink failed.

Deeper detail: [Architecture](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/architecture.md) · [ADR 0002](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/adr/0002-multi-sink-architecture.md).

## Features

- **Fast API scraping** — direct HKEx JSON API; no browser or Selenium.
- **Full history** — every filing from April 1999 to today, with chunk-level coverage checks.
- **Document processing** — PDF/HTML/Excel text and structured tables, extracted to Markdown.
- **Multi-sink** — any ordered combination of nine databases, each with native idempotent upserts.
- **AI-ready** — a hosted live MCP gateway plus a local stdio MCP server.
- **Resumable and observable** — batching, parallel downloads, stalled-job detection, per-sink
  counters, and `--coverage-report` / `--parity-report` / `--verify`.
- **Optional dependencies** — the core is `requests` + `beautifulsoup4`; drivers and document
  extraction are extras with graceful fallbacks.

## Documentation

- [Getting started](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/getting-started.md) · [Configuration](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/configuration.md) · [CLI](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/cli.md)
- [Database sinks (matrix)](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/README.md) — [PostgreSQL](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/postgresql.md), [MySQL/MariaDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/mysql.md), [SQLite](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/sqlite.md), [MongoDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/mongodb.md), [Neo4j](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/neo4j.md), [ClickHouse](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/clickhouse.md), [DuckDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/duckdb.md), [SurrealDB](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/sinks/surrealdb.md)
- [Live MCP gateway](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/live-mcp.md) · [AI agent support](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/ai-agents.md) · [MCP server](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/mcp.md)
- [Architecture](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/architecture.md) · [Troubleshooting](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/troubleshooting.md) · [Testing](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/testing.md)
- [Roadmap](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/roadmap.md) · [De-risking register](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/de-risking.md) · [Upgrading](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/upgrading.md)
- [What's new](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/news.md) · [Releasing](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/releasing.md) · [Legal & Terms of Use](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/legal.md) · [Changelog](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/CHANGELOG.md)
- **Docs site:** <https://hkex-listco-updates.ascent-partners.com/> · [Try it locally (`examples/`)](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/examples/README.md)

## Development

```bash
pip install -e ".[dev,all]"
ruff check           # lint (py310, line-length 100)
ruff format --check  # formatting
pytest               # unit tests (no DB or network required)
```

Tests are pure unit tests; SQLite and DuckDB contract tests run in-process, and integration
tests that need a server are skipped unless that sink is configured. See
[Testing](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/testing.md).

## Contributing

See [CONTRIBUTING.md](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/CONTRIBUTING.md); report security issues per [SECURITY.md](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/SECURITY.md).
Ideas and questions are welcome in
[Discussions](https://github.com/simonplmak-cloud/hkex-filing-scraper/discussions).

If this saves you time, a star helps others find it.

## License

MIT — see [LICENSE](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/LICENSE). That covers **this project's code only**; optional dependencies
carry their own licenses, notably the `pdf` extra (PyMuPDF / pymupdf4llm), which is
**AGPL-3.0** and deliberately excluded from `.[all]`. See
[docs/legal.md](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/legal.md#third-party-licenses).

**Data & Terms of Use:** this is a research tool for the undocumented HKEx JSON API, and it is
not affiliated with or endorsed by HKEx. Commercial redistribution of HKEx data may require a
licensed HKEx feed; see [docs/legal.md](https://github.com/simonplmak-cloud/hkex-filing-scraper/blob/HEAD/docs/legal.md).