Trade Me

The Trade Me MCP Server provides AI assistants with access to New Zealand’s Trade Me marketplace data. It exposes a wide range of catalogue, search, listing, and transaction-related operations via a lightweight MCP interface, enabling you to build powerful assistants that can explore categories, search for items, inspect listings, and manage bids or watchlists.

How to use

You interact with the server through a standard MCP client that runs your local server process and communicates over stdio. Start the server using the command shown below, then configure your MCP client to connect to the local process. You’ll be able to fetch category data, run searches across the marketplace, view listing details, and manage authenticated actions like watchlists and bids.

Typical end-to-end usage patterns include: 1) Discover categories and attributes to understand how listings are organized. 2) Run general and specialized searches (property, motors, jobs, services) to locate items of interest. 3) Retrieve detailed listing data, including photos, Q&A, and bidding history. 4) For authenticated tasks, manage your watchlist, place bids, make offers, or complete purchases.

To run the MCP server locally and connect your client, start the server process and point your client to the same local environment where the server is running. The server uses Python and is designed to be run as a local stdio MCP server, so your client should launch the Python module and establish the stdio channel for JSON-RPC style requests.

How to install

Prerequisites: ensure Python 3.11 or higher is installed on your system.

Install and run the MCP server locally by following these steps.

python -m trademe_mcp.server
```json
{
  "mcpServers": {
    "trademe": {
      "command": "python",
      "args": ["-m", "trademe_mcp.server"]
    }
  }
}

Additional setup and environment variables

You must provide Trade Me API credentials to access authenticated endpoints. These credentials are configured through environment variables. The key variables are the consumer key and secret, along with optional access token and token secret for authenticated operations. The environment also controls which Trade Me environment you target (sandbox or production) and the logging level.

# Run the server with required credentials
TRADEME_CONSUMER_KEY=your_consumer_key TRADEME_CONSUMER_SECRET=your_consumer_secret \
TRADEME_ENVIRONMENT=sandbox \
LOG_LEVEL=INFO \
python -m trademe_mcp.server
```json
{
  "TRADEME_CONSUMER_KEY": "your_consumer_key",
  "TRADEME_CONSUMER_SECRET": "your_consumer_secret",
  "TRADEME_ENVIRONMENT": "sandbox",
  "LOG_LEVEL": "INFO"
}

Security and credentials

Keep your API credentials secure. Do not expose your consumer key, consumer secret, or access tokens in client configurations that could be accessed by others. Use per-environment credentials and rotate tokens as needed.

Troubleshooting

If you encounter authentication errors, verify that your credentials are correct and that you are using the intended environment (sandbox vs production). Ensure Access Token and Token Secret are configured for authenticated endpoints.

For connection issues, confirm you can reach the local process and that your MCP client is configured to communicate over stdio with the running Python process.

Development notes

All available catalogue, search, listing, watchlist, and bidding actions are exposed as MCP tools. You can build AI workflows that fetch categories, run marketplace searches, retrieve listings, and perform authenticated actions like watching items or placing bids.

Available tools

get_categories

Retrieve the full Trade Me category tree with optional depth and counts.

get_category_details

Get detailed information about a specific category, including subcategories if provided.

get_localities

Retrieve all Trade Me localities (regions, districts, suburbs).

get_locality_details

Get details about a specific locality by its locality_id.

get_districts

Retrieve all Trade Me districts.

get_attributes

Get available attributes for a category.

get_legal_notice

Get legal notice text for a category.

search_general

Search the Trade Me marketplace across all categories with optional filters.

search_property_residential

Search for residential properties for sale with multiple filters.

search_property_rental

Search for rental properties with filters such as region, price, and date available.

search_property_commercial

Search for commercial real estate with filters like region and area.

search_motors

Search for motor vehicles including make, model, and year filters.

search_jobs

Search for job listings with keywords and regional filters.

search_services

Search for professional services and tradespeople by category and region.

get_listing_details

Get comprehensive details about a specific listing, including metadata if requested.

get_listing_photos

Retrieve all photos for a listing in multiple sizes.

get_listing_questions

Get Q&A for a listing with pagination support.

get_bidding_history

Get the bidding history for an auction listing.

get_shipping_options

Get available shipping methods and costs for a listing.

get_similar_listings

Find listings similar to a specified listing.

get_watchlist

Get the authenticated user’s watchlist.

add_to_watchlist

Add a listing to the authenticated user’s watchlist.

remove_from_watchlist

Remove a listing from the authenticated user’s watchlist.

place_bid

Place a bid on an auction listing.

buy_now

Purchase a listing using Buy Now.

make_offer

Make a fixed price offer on a listing.

withdraw_offer

Withdraw a previously made fixed price offer.

accept_offer

Accept an offer on your listing (seller action)

decline_offer

Decline an offer on your listing (seller action)

get_purchase_history

Get the authenticated user’s purchase history.

get_won_items

Get auctions the authenticated user has won.

get_lost_items

Get auctions the authenticated user bid on but lost.

get_bidding_on

Get items the authenticated user is currently bidding on.