Skip to main content
Glama

Trade Me MCP Server

by giussepe198
GitHub
Python
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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
-
license - not tested
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with New Zealand's largest online marketplace through the Trade Me API. Supports searching listings, managing watchlists, placing bids, making purchases, and accessing marketplace data across all Trade Me categories.

  1. Features
    1. Current Implementation
    2. Planned Features
  2. Installation
    1. Prerequisites
    2. Setup
    3. Environment Variables
  3. Usage
    1. Running the Server
    2. MCP Client Configuration
  4. Available Tools
    1. Catalogue Tools (No Authentication Required)
    2. Search Tools (No Authentication Required)
    3. Listing Retrieval Tools
    4. Watchlist Tools (Require Authentication)
    5. Bidding & Buying Tools (Require Authentication)
  5. Development
    1. Running Tests
    2. Code Quality
  6. API Documentation
    1. Getting Trade Me API Credentials
      1. Troubleshooting
        1. Authentication Errors
        2. Connection Issues
        3. Tool Errors
      2. Project Structure
        1. License
          1. Contributing
            1. Support

              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