Skip to main content
Glama

Trade Me MCP Server

by giussepe198
OverviewInspectNewSchemaRelated ServersScore
Python
Remote
  • Apple

Trade Me MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Trade Me API, enabling interaction with New Zealand's largest online marketplace.

Features

Current Implementation

Phase 1 - Foundation:

  • ✅ OAuth 1.0a authentication

  • ✅ Catalogue tools (no authentication required):

    • Get category tree

    • Get category details and attributes

    • Get localities and districts

    • Get legal notices

Phase 2 - Search & Discovery:

  • ✅ Search tools (no authentication required):

    • General marketplace search

    • Property search (residential, rental, commercial)

    • Motors search (cars, motorcycles, boats)

    • Jobs search

    • Services search

Phase 3 - Listing Retrieval:

  • ✅ Listing details and information:

    • Get listing details, photos, and Q&A

    • View bidding history and shipping options

    • Find similar listings

  • ✅ Watchlist management (requires authentication):

    • View watchlist

    • Add/remove items from watchlist

Phase 4 - Bidding & Buying:

  • ✅ Bidding tools (requires authentication):

    • Place bids on auctions

    • Buy Now purchases

    • View won/lost auctions

    • View current bids

  • ✅ Offers (requires authentication):

    • Make fixed price offers

    • Withdraw offers

    • Accept/decline offers (seller)

  • ✅ Purchase management (requires authentication):

    • View purchase history

Planned Features

  • Selling and listing management

  • User account management

  • Saved searches and favourites

Installation

Prerequisites

Setup

  1. Clone the repository:

git clone <repository-url> cd trademe-mcp

  1. Create a virtual environment:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

  1. Install dependencies:

pip install -e .

  1. Configure environment variables:

cp .env.example .env # Edit .env with your Trade Me API credentials

Environment Variables

# Required TRADEME_CONSUMER_KEY=your_consumer_key TRADEME_CONSUMER_SECRET=your_consumer_secret # Optional (required for authenticated endpoints) TRADEME_ACCESS_TOKEN=your_access_token TRADEME_ACCESS_TOKEN_SECRET=your_token_secret # Configuration TRADEME_ENVIRONMENT=sandbox # or 'production' LOG_LEVEL=INFO

Usage

Running the Server

python -m trademe_mcp.server

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "trademe": { "command": "python", "args": ["-m", "trademe_mcp.server"], "env": { "TRADEME_CONSUMER_KEY": "your_consumer_key", "TRADEME_CONSUMER_SECRET": "your_consumer_secret", "TRADEME_ENVIRONMENT": "sandbox" } } } }

Other MCP Clients

The server uses standard MCP protocol over stdio. Configure your client to run:

python -m trademe_mcp.server

Available Tools

Catalogue Tools (No Authentication Required)

get_categories

Retrieve the full Trade Me category tree.

Parameters:

  • depth (optional): Limit subcategory depth (1-4)

  • with_counts (optional): Include listing counts (boolean)

Example:

{ "depth": 2, "with_counts": true }

get_category_details

Get detailed information about a specific category.

Parameters:

  • category_number (required): Trade Me category number (e.g., "0004-0369-6076-")

  • depth (optional): Limit subcategory depth

Example:

{ "category_number": "0004-0369-6076-", "depth": 1 }

get_localities

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

Example:

{}

get_locality_details

Get details about a specific locality.

Parameters:

  • locality_id (required): The locality ID number

Example:

{ "locality_id": 100 }

get_districts

Retrieve all Trade Me districts.

Example:

{}

get_attributes

Get available attributes for a category.

Parameters:

  • category_number (required): Trade Me category number

Example:

{ "category_number": "0004-0369-6076-" }

get_legal_notice

Get legal notice text for a category.

Parameters:

  • category_number (required): Trade Me category number

Example:

{ "category_number": "0004-0369-6076-" }

Search Tools (No Authentication Required)

search_general

Search the Trade Me marketplace across all categories.

Parameters:

  • search_string (optional): Search keywords

  • category (optional): Category number to filter by

  • price_min (optional): Minimum price

  • price_max (optional): Maximum price

  • condition (optional): Item condition (New, Used, Refurbished)

  • buy_now_only (optional): Only show Buy Now listings

  • region (optional): Region ID

  • district (optional): District ID

  • suburb (optional): Suburb ID

  • page (optional): Page number (default: 1)

  • rows (optional): Results per page (default: 25, max: 500)

  • sort_order (optional): Sort order (Default, ExpiryAsc, ExpiryDesc, PriceAsc, PriceDesc, Featured)

Example:

{ "search_string": "laptop", "price_max": 1000, "condition": "New", "rows": 50 }

search_property_residential

Search for residential properties for sale.

Parameters:

  • search_string (optional): Search keywords

  • region (optional): Region ID

  • district (optional): District ID

  • suburb (optional): Suburb ID

  • price_min (optional): Minimum price

  • price_max (optional): Maximum price

  • bedrooms_min (optional): Minimum bedrooms

  • bedrooms_max (optional): Maximum bedrooms

  • bathrooms_min (optional): Minimum bathrooms

  • property_type (optional): Property type (House, Apartment, Townhouse, Unit, Land)

  • adjacent_suburbs (optional): Include adjacent suburbs

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "region": 9, "bedrooms_min": 3, "price_max": 800000, "property_type": "House" }

search_property_rental

Search for rental properties.

Parameters:

  • search_string (optional): Search keywords

  • region (optional): Region ID

  • district (optional): District ID

  • suburb (optional): Suburb ID

  • price_min (optional): Minimum weekly rent

  • price_max (optional): Maximum weekly rent

  • bedrooms_min (optional): Minimum bedrooms

  • bedrooms_max (optional): Maximum bedrooms

  • property_type (optional): Property type

  • pets_ok (optional): Allow pets

  • smokers_ok (optional): Allow smokers

  • date_available (optional): Date available from (YYYY-MM-DD)

  • adjacent_suburbs (optional): Include adjacent suburbs

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "region": 9, "bedrooms_min": 2, "price_max": 500, "pets_ok": true }

search_property_commercial

Search for commercial real estate.

Parameters:

  • search_string (optional): Search keywords

  • region (optional): Region ID

  • district (optional): District ID

  • suburb (optional): Suburb ID

  • price_min (optional): Minimum price

  • price_max (optional): Maximum price

  • property_type (optional): Commercial property type (Office, Retail, Industrial, Land)

  • area_min (optional): Minimum floor area (sqm)

  • area_max (optional): Maximum floor area (sqm)

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "property_type": "Office", "region": 9, "area_min": 100 }

search_motors

Search for motor vehicles.

Parameters:

  • search_string (optional): Search keywords (make/model)

  • category (optional): Motors category

  • price_min (optional): Minimum price

  • price_max (optional): Maximum price

  • year_min (optional): Minimum year

  • year_max (optional): Maximum year

  • odometer_min (optional): Minimum odometer reading (km)

  • odometer_max (optional): Maximum odometer reading (km)

  • make (optional): Vehicle make

  • model (optional): Vehicle model

  • body_style (optional): Body style (Sedan, SUV, Hatchback, etc.)

  • transmission (optional): Transmission type (Automatic, Manual)

  • fuel_type (optional): Fuel type (Petrol, Diesel, Electric, Hybrid)

  • engine_size_min (optional): Minimum engine size (cc)

  • engine_size_max (optional): Maximum engine size (cc)

  • region (optional): Region ID

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "make": "Toyota", "year_min": 2015, "price_max": 25000, "transmission": "Automatic" }

search_jobs

Search for job listings.

Parameters:

  • search_string (optional): Search keywords (job title, company)

  • category (optional): Jobs category number

  • region (optional): Region ID

  • district (optional): District ID

  • type (optional): Job type (FullTime, PartTime, Contract, Casual, Temporary)

  • pay_min (optional): Minimum salary/pay

  • pay_max (optional): Maximum salary/pay

  • pay_type (optional): Pay period (Annual, Hourly, Daily)

  • work_type (optional): Work arrangement (Office, Remote, Hybrid)

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "search_string": "software developer", "region": 9, "type": "FullTime", "pay_min": 80000 }

search_services

Search for professional services and tradespeople.

Parameters:

  • search_string (optional): Search keywords

  • category (optional): Services category number

  • region (optional): Region ID

  • district (optional): District ID

  • suburb (optional): Suburb ID

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "search_string": "plumber", "region": 9 }

Listing Retrieval Tools

get_listing_details

Get comprehensive details about a specific listing.

Parameters:

  • listing_id (required): The Trade Me listing ID

  • return_metadata (optional): Include additional metadata

Example:

{ "listing_id": 4567890123 }

get_listing_photos

Get all photos for a listing in various sizes.

Parameters:

  • listing_id (required): The Trade Me listing ID

Example:

{ "listing_id": 4567890123 }

get_listing_questions

Get questions and answers (Q&A) for a listing.

Parameters:

  • listing_id (required): The Trade Me listing ID

  • page (optional): Page number for pagination

  • rows (optional): Number of results per page

Example:

{ "listing_id": 4567890123, "page": 1, "rows": 20 }

get_bidding_history

Get the bidding history for an auction listing.

Parameters:

  • listing_id (required): The Trade Me listing ID

Example:

{ "listing_id": 4567890123 }

get_shipping_options

Get available shipping methods and costs.

Parameters:

  • listing_id (required): The Trade Me listing ID

Example:

{ "listing_id": 4567890123 }

get_similar_listings

Find listings similar to a specified listing.

Parameters:

  • listing_id (required): The Trade Me listing ID

  • rows (optional): Number of results to return

Example:

{ "listing_id": 4567890123, "rows": 20 }

Watchlist Tools (Require Authentication)

get_watchlist

Get the authenticated user's watchlist.

Parameters:

  • category (optional): Filter by category number

  • page (optional): Page number

  • rows (optional): Results per page (max 500)

Example:

{ "page": 1, "rows": 50 }

add_to_watchlist

Add a listing to the authenticated user's watchlist.

Parameters:

  • listing_id (required): The Trade Me listing ID to watch

  • email_option (optional): Email notification preference (0=None, 1=Daily, 2=Immediate)

Example:

{ "listing_id": 4567890123, "email_option": 1 }

remove_from_watchlist

Remove a listing from the authenticated user's watchlist.

Parameters:

  • listing_id (required): The Trade Me listing ID to unwatch

Example:

{ "listing_id": 4567890123 }

Bidding & Buying Tools (Require Authentication)

place_bid

Place a bid on an auction listing.

Parameters:

  • listing_id (required): The Trade Me listing ID to bid on

  • amount (required): The bid amount in NZD

  • shipping_option (optional): Shipping option ID

Example:

{ "listing_id": 4567890123, "amount": 150.00 }

buy_now

Purchase a listing using Buy Now.

Parameters:

  • listing_id (required): The Trade Me listing ID to purchase

  • quantity (optional): Number of items to purchase (default: 1)

  • shipping_option (optional): Shipping option ID

  • accept_terms (optional): Accept seller's terms and conditions

Example:

{ "listing_id": 4567890123, "quantity": 1, "accept_terms": true }

make_offer

Make a fixed price offer on a listing.

Parameters:

  • listing_id (required): The Trade Me listing ID

  • price (required): The offer amount in NZD

  • message (optional): Optional message to seller

Example:

{ "listing_id": 4567890123, "price": 500.00, "message": "Is this negotiable?" }

withdraw_offer

Withdraw a previously made fixed price offer.

Parameters:

  • offer_id (required): The offer ID to withdraw

Example:

{ "offer_id": 123456 }

accept_offer

Accept an offer made on your listing (seller action).

Parameters:

  • offer_id (required): The offer ID to accept

Example:

{ "offer_id": 123456 }

decline_offer

Decline an offer made on your listing (seller action).

Parameters:

  • offer_id (required): The offer ID to decline

Example:

{ "offer_id": 123456 }

get_purchase_history

Get the authenticated user's purchase history.

Parameters:

  • page (optional): Page number for pagination

  • rows (optional): Results per page (max 500)

  • filter (optional): Filter by status (All, EmailSent, PaymentReceived, GoodsShipped)

Example:

{ "page": 1, "rows": 50, "filter": "All" }

get_won_items

Get auctions the authenticated user has won.

Parameters:

  • page (optional): Page number for pagination

  • rows (optional): Results per page (max 500)

Example:

{ "page": 1, "rows": 25 }

get_lost_items

Get auctions the authenticated user bid on but lost.

Parameters:

  • page (optional): Page number for pagination

  • rows (optional): Results per page (max 500)

Example:

{ "page": 1, "rows": 25 }

get_bidding_on

Get items the authenticated user is currently bidding on.

Parameters:

  • page (optional): Page number for pagination

  • rows (optional): Results per page (max 500)

Example:

{ "page": 1, "rows": 25 }

Development

Running Tests

# Install dev dependencies pip install -e ".[dev]" # Run tests pytest # Run with coverage pytest --cov=trademe_mcp

Code Quality

# Format code black src tests # Lint ruff check src tests # Type checking mypy src

API Documentation

Getting Trade Me API Credentials

  1. Register for a Trade Me account

  2. Go to Developer Options

  3. Create a new application

  4. Note your Consumer Key and Consumer Secret

  5. For authenticated endpoints, complete OAuth flow to get Access Token and Token Secret

Troubleshooting

Authentication Errors

  • Verify your API credentials are correct

  • Check you're using the right environment (sandbox vs production)

  • Ensure Access Token is set for authenticated endpoints

Connection Issues

  • Confirm you have internet connectivity

  • Check if Trade Me API is accessible

  • Verify firewall settings

Tool Errors

  • Check the tool parameters match the schema

  • Review server logs for detailed error messages

  • Ensure category numbers are in correct format (e.g., "0004-0369-6076-")

Project Structure

trademe-mcp/ ├── src/trademe_mcp/ │ ├── __init__.py │ ├── server.py # Main MCP server │ ├── auth.py # OAuth 1.0a implementation │ ├── client.py # Trade Me API client │ └── tools/ │ ├── __init__.py │ └── catalogue.py # Catalogue tools ├── tests/ ├── .env.example ├── .gitignore ├── pyproject.toml └── README.md

License

[Your License Here]

Contributing

Contributions are welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request

Support

For issues and questions:

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Related Resources

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/giussepe198/trademe-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server