au-trademark-trends-mcp

au-trademark-trends-mcp

An MCP server for Australian trade mark trends, built on IP Australia's opendata 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 widetable - applicant, country, mark text and class count are all flattened intoit - 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 callsthrough the official client):

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

Run the tm_sql guard tests, which assert the escape hatch cannot reach thefilesystem 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 tothe 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 trustthe project's MCP servers. No paths to edit.

To use it from any directory, register it at user scope instead. This needsabsolute 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 arethe only option. Edit %APPDATA%\Claude\claude_desktop_config.json, and notethat 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 thewindow 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

Tables

Applicant entity resolution

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

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

etl/entities.py treats (party_id, normalised_name) asedges of a bipartite graph and takes its connected components, merging in bothdirections 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 nomatching edge, so they cannot pool unrelated companies.

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

tm_applicant_ranking groups by entity by default; passgroup_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 countsapplications; with a class filter it counts class filings, so an applicationcovering 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. Donot read the final period as a decline.
• Status is a snapshot, not an examination outcome. dead includes marksthat registered and later lapsed or ceased. A high pending share in the lasttwo or three cohorts is expected, not a signal.
• Keyword search covers mark text only, not goods and services text. Marktext exists for 96.3% of applications.
• per_10k_filings is more trustworthy than a raw count. It normalisesagainst total filing volume, separating a real trend from overall marketgrowth.
• Individual applicant names are pseudonymised upstream and cannot berecovered. Only organisation names are real.
• Applicant rows are corporate groups by default. Entity resolution isname-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 howmany names went into a row.
• Filings are attributed to the founding applicant, so later assignments donot move them.
• Madrid exports have no destination country. The source records only that amark 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 throughparty_activity.csv.

Not loaded yet

application_events.csv (4.2GB, 31.7M trade mark events) is not loaded. Itwould unlock adverse examination rates, opposition rates, renewal rates and truestage-by-stage pendency. Adding it is one more block in the ETL - the eventtypes 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 intellectualproperty 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; theserver needs no changes.

The source CSVs and the built database are gitignored - 10.4GB in total, wellpast 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 ownterms. Confirm the current licence on thedataset page before redistributingthe data or any derived dataset, and attribute IP Australia as the source.