# hk-ipo-fee-mcp

<!-- mcp-name: io.github.tiezhengzhang/hk-ipo-fee-mcp -->

[![PyPI](https://img.shields.io/pypi/v/hk-ipo-fee-mcp)](https://pypi.org/project/hk-ipo-fee-mcp/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) server that gives AI assistants **exact Hong Kong IPO cost maths**, so they can stop guessing. It covers:

- the entry fee (amount payable), including the 1% brokerage, SFC, AFRC and trading-fee levies, each rounded to the cent;
- margin-financing interest, the **break-even sell price**, scenario P&L and expected value;
- selling costs, with stamp duty rounded up to a whole HK$;
- cited rule summaries (Mechanism A/B allocation, Pool A/B, FINI T+2);
- open-licensed (Wikidata, CC0) lookups of HK-listed companies and listing dates.

> **中文简介**：港股打新费用计算 MCP 服务器。让 Claude、Cursor 等 AI 助手精确计算入场费（1% 佣金 + 证监会/会财局征费 + 交易费，逐项四舍五入至分）、孖展利息、回本价、情景盈亏与期望值、卖出费用（印花税向上取整至元），并查询机制 A/B、甲乙组、FINI 等规则（附出处）。公司与上市日期查询只使用 Wikidata（CC0）开放数据，**不抓取港交所/披露易**。免费开源（MIT）。网页版计算器：<https://hk-ipo-calc.pages.dev/>

Ask things like:

> *"I'm applying for 20 lots of an IPO at HK$8.88, 500 shares a lot, with 10× margin at 3.5% for 7 days and a HK$100 handling fee. 18,000 out of 120,000 applicants at my size got one lot. What's my entry fee, break-even price and expected value?"*

The numbers come from a tested fee engine, not from the model. That engine is the same one used by the [web calculator](https://hk-ipo-calc.pages.dev/) and the *HK IPO Ledger* Chrome extension, and the two implementations are checked to give identical results on 8,000 test values.

## Tools

| Tool | What it does |
|---|---|
| `hk_ipo_amount_payable` | Amount payable for N shares: application money + 1% brokerage + 0.0027% SFC levy + 0.00015% AFRC levy + 0.00565% trading fee |
| `hk_ipo_plan` | Full plan: entry fee, total payable, own cash vs margin loan, interest, fixed cost, break-even price, scenario table, expected value (from allotment counts or a rate) |
| `hk_sell_costs` | Selling costs: 0.1% stamp duty rounded **up** to HK$1, trading fee, levies, broker commission / platform fee |
| `hk_ipo_rules` | Cited rule summaries: `fees`, `allocation` (Mechanism A/B from 4 Aug 2025, 18C), `pools`, `timeline` (FINI) or `all` |
| `hk_company_lookup` | Look up an HK-listed company by code or name (Wikidata, CC0) |
| `hk_listings` | Listings by date range (Wikidata, CC0, cached 24 h) |

## Install

You need Python ≥ 3.10. The easiest way to run it is with [uv](https://docs.astral.sh/uv/), which needs no install step:

```bash
uvx hk-ipo-fee-mcp          # runs the stdio server
# or
pipx install hk-ipo-fee-mcp && hk-ipo-fee-mcp
```

### Claude Desktop

Edit `claude_desktop_config.json`. On macOS it is at `~/Library/Application Support/Claude/`; on Windows at `%APPDATA%\Claude\`.

```json
{
  "mcpServers": {
    "hk-ipo-fee": { "command": "uvx", "args": ["hk-ipo-fee-mcp"] }
  }
}
```

### Claude Code

```bash
claude mcp add hk-ipo-fee -- uvx hk-ipo-fee-mcp
```

### Cursor

Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project:

```json
{
  "mcpServers": {
    "hk-ipo-fee": { "command": "uvx", "args": ["hk-ipo-fee-mcp"] }
  }
}
```

### VS Code (GitHub Copilot agent mode)

Add this to `.vscode/mcp.json`:

```json
{
  "servers": {
    "hk-ipo-fee": { "type": "stdio", "command": "uvx", "args": ["hk-ipo-fee-mcp"] }
  }
}
```

### Windsurf / Cline / other clients

Any client that speaks MCP over stdio works. Set the command to `uvx` and the args to `["hk-ipo-fee-mcp"]`. If you installed with pipx, set the command to `hk-ipo-fee-mcp` with no args.

### Environment variables (optional)

| Variable | Default | Purpose |
|---|---|---|
| `HKIPO_CONTACT` | project URL + maintainer email | Contact string in the Wikidata User-Agent ([Wikimedia UA policy](https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy)). Set your own if you query a lot |
| `HK_IPO_FEE_MCP_CACHE` | `~/.cache/hk-ipo-fee-mcp` | Cache directory for listing data |

## Example

`hk_ipo_plan(offer_price=8.88, board_lot=500, lots_applied=20, margin_multiple=10, annual_rate=0.035, interest_days=7, handling_fee=100, allotted_lots=1, valid_applications=120000, successful_applicants=18000)` returns:

| | |
|---|---|
| Entry fee (1 lot) | HK$4,484.78 |
| Total amount payable (20 lots) | HK$89,695.55 |
| Margin interest | HK$54.19 |
| Fixed cost (paid either way) | HK$154.19 |
| Break-even sell price | HK$9.289 (+4.61%), assuming zero sell commission |

*(These are illustrative inputs, not a real IPO.)*

## Data & compliance

- **Fees and rules** follow published SFC, AFRC, HKEX and IRD (GovHK) rates; every rule summary cites its source.
- **No HKEX/HKEXnews scraping.** HKEX's terms prohibit automated access, so IPO terms (offer price, board lot, allotment results) must come from you or the prospectus. The server never invents them.
- **Listing lookups** use [Wikidata](https://www.wikidata.org/) (CC0). The data is community-maintained, so verify it before relying on it.
- Results are arithmetic, **not investment advice**. This project is not affiliated with Hong Kong Exchanges and Clearing Limited.

## Development

```bash
git clone https://github.com/tiezhengzhang/hk-ipo-fee-mcp && cd hk-ipo-fee-mcp
python -m venv .venv && . .venv/bin/activate && pip install -e . pytest
python -m pytest -q                 # fee anchors + MCP stdio end-to-end
```

## More from the author

- 🧮 **[HK IPO Calculator](https://hk-ipo-calc.pages.dev/)** — a free bilingual web calculator using the same fee engine, plus guides on Mechanism A/B, Pool A/B, margin and fees.
- 📒 **[HK IPO Ledger (Chrome extension)](https://hk-ipo-calc.pages.dev/extension/)** — an IPO ledger across multiple brokers, with allotment and P&L stats, kept on your device. Free for up to 30 records. [Pro](https://hk-ipo-calc.pages.dev/pricing/) is a one-time payment with no subscription.

## License

[MIT](LICENSE) © 2026 Tiezheng Zhang. Listing data from Wikidata is CC0.