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

• Python 3.11 or higher
• Trade Me API credentials (Get them here)

Setup

1. Clone the repository:

git clone <repository-url>
cd trademe-mcp

2. Create a virtual environment:

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

3. Install dependencies:

pip install -e .

4. 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

• Trade Me API Reference
• Trade Me Sandbox
• MCP 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:

• Trade Me API: Developer Documentation
• MCP Protocol: MCP Documentation
• This project: GitHub Issues