@pipeworx/china-customs

China's official monthly merchandise trade statistics — total exports/imports/balance, by trading partner, by HS commodity section/chapter, and trade indices — scraped from the General Administration of Customs (GACC) English-language site, which is reachable where the mainland Chinese statistics database (stats.customs.gov.cn) 412-blocks non-China IPs.

Part of Pipeworx — an MCP gateway connecting AI agents to 1573+ live data sources.

Tools

• china_trade_summary({ month? }) — total exports/imports/balance in both USD and CNY (100-million units), with official month-on-month and year-on-year % changes, from GACC's "preliminary" flash release.
• china_trade_by_country({ month?, partner? }) — exports/imports/balance by trading partner country/region, month + year-to-date, with YoY %, from GACC's "final" monthly release. partner is an optional substring filter (e.g. "United States", "Japan", "Asia").
• china_trade_by_commodity({ month?, hs_section? }) — exports/imports by HS Section (21 sections) and 2-digit HS chapter (Division), month + year-to-date, with YoY %. Without hs_section, returns TOTAL + the 21 sections; with it (a 2-digit HS chapter code like "84", or free text like "machinery"), also returns that section's individual chapters.
• china_trade_indices({ month?, direction?, series?, chained?, hs2? }) — unit-value / quantum / value indices for exports or imports, base = same month of the prior year = 100. series: hs2 (default), sitc2, bec, industry, hs4, sitc3. chained selects the chained-index variant. Pass a 2-digit hs2 chapter code to drill into one chapter. Chapter/section labels in this specific GACC table are Chinese-only — cross-reference the HS2 code against china_trade_by_commodity for the English name.

Auth

Keyless. GACC's English site (english.customs.gov.cn) serves these pages with no authentication.

Data sources

• http://english.customs.gov.cn/statics/report/monthly.html — index of the "final" revised monthly report categories (18 tables, USD only): summary, by country/region, by HS section/division, by customs regime, major commodities, etc.
• http://english.customs.gov.cn/statics/report/preliminary.html — index of the "preliminary" flash-release tables (USD and CNY), published on a shorter lag than the final tables and carrying GACC's own month-on-month/year-on-year % figures.
• http://english.customs.gov.cn/statics/report/trade.html — index of trade-index tables (unit value/quantum/value, chained and non-chained, by HS2/SITC2/BEC/Industry/HS4/SITC3, for both exports and imports).

HTTPS does not work — the site resets the connection over TLS from this environment (checked 2026-09-07); use plain http://.

The tables are real HTML, not images or client-rendered — this was the open question the task started from. Fetching the raw HTML with a plain UA and parsing the <table> proves it: GACC's monthly.html report page for July 2026 (http://english.customs.gov.cn/Statics/ec4779c4-69ac-4c1b-8792-1f2d0f423103.html) contains the row 2026.07 | Total 683,366 | Export 397,852 | Import 285,514 | Balance 112,337 (US$ million) directly in the markup.

Index pages link to per-month report pages, and the links are NOT derivable from the date — each index table row has one cell per report category, and within that cell one <a href> per calendar month that's been published so far this year (an un-linked <span>Aug.</span> instead of <a href>Aug.</a> means that month isn't out yet). The linked URL is an opaque GUID (/Statics/<uuid>.html) that changes every time GACC republishes, so every tool call re-parses the relevant index page (cached 6h per isolate) to find the right link before fetching the report itself — there is no way to construct the report URL from a month number alone.

The three families of report pages have different scopes and different HTML layouts:

• monthly.html's "(1) Summary … Monthly" report is a trailing table — any one month's link (e.g. "Jul.") returns a table with roughly the last 19 months of history (2025.01 through 2026.07 as of this build), one row per YYYY.MM. Its other rows (by country, by HS section, etc.) are single-month snapshots (current month + year-to-date only) — fetching an older month requires that specific month's own link.
• preliminary.html's tables are single-month snapshots per link, with GACC's own MoM%/YoY% baked in. Data cells are <span>value</span>.
• trade.html's index tables use a different, Word-pasted HTML shape (<td><p>…</p></td>, sometimes two <p> lines per cell for bilingual headers) and are Chinese-only for individual section/chapter names — only the numeric HS2 code is bilingual-safe.
• January is sometimes missing from preliminary.html's linked months (GACC often reports the first two months combined due to the Lunar New Year distortion) — don't assume every month 1–12 has a link.

Publication lag: the "preliminary" release typically appears about a week after month-end; a revised "final" figure (used by china_trade_by_country and china_trade_by_commodity) follows in GACC's next monthly cycle. china_trade_summary's response always states the actual period it read (period_label), and each tool lists available_months — the calendar months currently linked on the relevant GACC index page — so a caller can see the real freshness rather than assume today's month is covered.

A requested month outside the linked range is a clear error, not a silent substitution. month only ever matches by month-NUMBER against the index page (which never states a year); the actual period fetched is always read back out of the report page itself and returned as period_label, so a wrong-year guess surfaces as a visible mismatch rather than mislabeling the data.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "china-customs": {
      "url": "https://gateway.pipeworx.io/china-customs/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/china-customs/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

Both URLs reach the same gateway and the same 1573+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

{
  "mcpServers": {
    "china-customs": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-china-customs"]
    }
  }
}

Or run it directly to confirm it starts:

npx -y @pipeworx/mcp-china-customs

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

ask_pipeworx({ question: "your question about China Customs data" })

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides
• pipeworx.io

License

MIT