au-trademark-trends-mcp

An MCP server for Australian trade mark trends, built on IP Australia's open data at data.gov.au/data/dataset/iprapid. Python + DuckDB.

Architecture

5 CSVs (5.2GB) ──→ etl/build_db.py ──→ data/tm.duckdb (995MB) ──→ src/server.py (MCP)
                   DuckDB reads CSV     6 normalised tables       12 tools, 10-800ms
                   directly             + 1 wide table

The ETL runs in about 47 seconds. tm_application is a denormalised wide table - applicant, country, mark text and class count are all flattened into it - so the common query is a single-table scan with no joins.

Setup

python -m venv .venv

.venv\Scripts\python.exe -m pip install -r requirements.txt

Build the database (needs the five CSVs in the project root, about 33 seconds):

.venv\Scripts\python.exe etl\build_db.py

Run the end-to-end test (spawns a real MCP server and makes 20 tool calls through the official client):

.venv\Scripts\python.exe test\smoke.py

Run the tm_sql guard tests, which assert the escape hatch cannot reach the filesystem or the network:

.venv\Scripts\python.exe test\test_sql_guard.py

Connecting

Claude Code - the repository ships a .mcp.json whose paths are relative to the project root, so a clone works as soon as the dependencies are installed. Start Claude Code in the project directory; the first run asks whether you trust the project's MCP servers. No paths to edit.

To use it from any directory, register it at user scope instead. This needs absolute paths - replace <project path> with your own:

claude mcp add -s user au-trademark-trends -- "<project path>/.venv/Scripts/python.exe" "<project path>/src/server.py"

Claude Desktop has no concept of a project directory, so absolute paths are the only option. Edit %APPDATA%\Claude\claude_desktop_config.json, and note that backslashes must be doubled inside JSON:

{
  "mcpServers": {
    "au-trademark-trends": {
      "command": "<project path>\\.venv\\Scripts\\python.exe",
      "args": ["<project path>\\src\\server.py"]
    }
  }
}

Quit Claude Desktop completely and restart it afterwards - closing the window is not enough, exit it from the system tray.

On Linux and macOS, use .venv/bin/python in place of .venv/Scripts/python.exe.

The 12 tools

Tool	Answers
tm_dataset_info	Coverage, freshness, and what it explicitly cannot answer
tm_filing_trend	Filing volume over time, split by class, outcome or origin; yearly, quarterly or monthly
tm_class_ranking	Which Nice classes are rising or falling against an equal-length baseline
tm_registration_outcomes	Registration, lapse and refusal rates, plus average time to registration
tm_keyword_trend	A word's trend in brand names, with a per_10k_filings normalised rate
tm_keyword_examples	The actual marks a keyword matched, to check it measures what you think
tm_applicant_ranking	Leading applicants with growth and registration rates, merged into corporate groups
tm_applicant_profile	One group's filing history, main classes and usual agents
tm_origin_trend	Domestic versus foreign share, and the leading source countries
tm_madrid_flow	Madrid Protocol flow in and out of Australia; imports split by origin and class
tm_render_chart	Renders a self-contained SVG into charts/
tm_sql	Read-only SQL escape hatch for questions the other tools do not cover

Tables

Table	Rows	Grain
tm_application	2,314,887	One row per application, denormalised
tm_class	3,727,611	Application x Nice class
tm_mark	5,345,477	Application x mark text representation
tm_mark_primary	2,228,469	One searchable headline mark text per application
tm_party	7,656,643	Application x party (applicant, agent, opponent)
tm_applicant_primary	2,314,679	The founding applicant of each application
tm_applicant_entity	674,221	party_id to resolved corporate group
tm_link	1,428,159	Madrid, convention priority, related applications

Applicant entity resolution

Neither identifier in the source data is a usable company key on its own. They are many-to-many in both directions: one party_id can carry 19 different names, and avon products inc spans 4 different party_id values across 1,975 filings. Nestlé is scattered across more than ten id/name pairs.

This changes answers. Ranked by legal name, the top 2021-2025 applicant is Novartis on 484 filings. But Aristocrat filed 476 as aristocrat technologies australia pty ltd and another 288 as aristocrat technologies inc - as a group it leads with 767.

etl/entities.py treats (party_id, normalised_name) as edges of a bipartite graph and takes its connected components, merging in both directions at once. Names are normalised by stripping trading-as clauses, punctuation, a leading article and trailing legal-form tokens (pty ltd, gmbh, kabushiki kaisha, …). Names that are nothing but a legal form get no matching edge, so they cannot pool unrelated companies.

The result is deliberately conservative - 674,221 party ids collapse to 638,142 groups, and no component exceeds 12 ids:

Group size	Count
1 (unmerged)	606,306
2	28,612
3-5	3,169
6-10	66
11-50	1
51+	0

tm_applicant_ranking groups by entity by default; pass group_by="legal_name" for the raw entities.

Counting rules and traps

Every tool returns a caveats field. Pass it on when reporting results.

• applications vs class_filings. With no class filter the metric counts applications; with a class filter it counts class filings, so an application covering three classes is counted three times. The metric field says which.
• The trailing period is always incomplete. Data runs through 2026-08. partial_buckets flags the affected periods and charts shade them grey. Do not read the final period as a decline.
• Status is a snapshot, not an examination outcome. dead includes marks that registered and later lapsed or ceased. A high pending share in the last two or three cohorts is expected, not a signal.
• Keyword search covers mark text only, not goods and services text. Mark text exists for 96.3% of applications.
• per_10k_filings is more trustworthy than a raw count. It normalises against total filing volume, separating a real trend from overall market growth.
• Individual applicant names are pseudonymised upstream and cannot be recovered. Only organisation names are real.
• Applicant rows are corporate groups by default. Entity resolution is name-based and conservative, so unrelated companies sharing a plain name (several "Delta" companies) can still be pooled, and misspelt names (aristocrat technolgies) stay separate. legal_entities_merged shows how many names went into a row.
• Filings are attributed to the founding applicant, so later assignments do not move them.
• Madrid exports have no destination country. The source records only that a mark went out, so a total is all that is available.
• The CSVs escape quotes with a backslash (\") rather than doubling them, so read_csv needs escape='\' or it fails partway through party_activity.csv.

Not loaded yet

application_events.csv (4.2GB, 31.7M trade mark events) is not loaded. It would unlock adverse examination rates, opposition rates, renewal rates and true stage-by-stage pendency. Adding it is one more block in the ETL - the event types are already confirmed: exam_outcome_adverse 1.36M, published_opp_lodged 26,834, removed_non_use 6,495.

Data source

https://data.gov.au/data/dataset/iprapid - IP Australia's intellectual property rights open data, published on data.gov.au and updated periodically. Drop replacement CSVs in the project root and re-run etl/build_db.py; the server needs no changes.

The source CSVs and the built database are gitignored - 10.4GB in total, well past GitHub's limits. The five files needed are:

application.csv                 720 MB
application_classification.csv  2.0 GB
application_description.csv     451 MB
application_links.csv           271 MB
party_activity.csv              1.8 GB

Licence

The code is MIT - see LICENSE.

That does not extend to the data, which IP Australia publishes under its own terms. Confirm the current licence on the dataset page before redistributing the data or any derived dataset, and attribute IP Australia as the source.