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
- Clone the repository:
git clone <repository-url>
cd trademe-mcp
- Create a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -e .
- 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 keywordscategory(optional): Category number to filter byprice_min(optional): Minimum priceprice_max(optional): Maximum pricecondition(optional): Item condition (New, Used, Refurbished)buy_now_only(optional): Only show Buy Now listingsregion(optional): Region IDdistrict(optional): District IDsuburb(optional): Suburb IDpage(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 keywordsregion(optional): Region IDdistrict(optional): District IDsuburb(optional): Suburb IDprice_min(optional): Minimum priceprice_max(optional): Maximum pricebedrooms_min(optional): Minimum bedroomsbedrooms_max(optional): Maximum bedroomsbathrooms_min(optional): Minimum bathroomsproperty_type(optional): Property type (House, Apartment, Townhouse, Unit, Land)adjacent_suburbs(optional): Include adjacent suburbspage(optional): Page numberrows(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 keywordsregion(optional): Region IDdistrict(optional): District IDsuburb(optional): Suburb IDprice_min(optional): Minimum weekly rentprice_max(optional): Maximum weekly rentbedrooms_min(optional): Minimum bedroomsbedrooms_max(optional): Maximum bedroomsproperty_type(optional): Property typepets_ok(optional): Allow petssmokers_ok(optional): Allow smokersdate_available(optional): Date available from (YYYY-MM-DD)adjacent_suburbs(optional): Include adjacent suburbspage(optional): Page numberrows(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 keywordsregion(optional): Region IDdistrict(optional): District IDsuburb(optional): Suburb IDprice_min(optional): Minimum priceprice_max(optional): Maximum priceproperty_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 numberrows(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 categoryprice_min(optional): Minimum priceprice_max(optional): Maximum priceyear_min(optional): Minimum yearyear_max(optional): Maximum yearodometer_min(optional): Minimum odometer reading (km)odometer_max(optional): Maximum odometer reading (km)make(optional): Vehicle makemodel(optional): Vehicle modelbody_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 IDpage(optional): Page numberrows(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 numberregion(optional): Region IDdistrict(optional): District IDtype(optional): Job type (FullTime, PartTime, Contract, Casual, Temporary)pay_min(optional): Minimum salary/paypay_max(optional): Maximum salary/paypay_type(optional): Pay period (Annual, Hourly, Daily)work_type(optional): Work arrangement (Office, Remote, Hybrid)page(optional): Page numberrows(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 keywordscategory(optional): Services category numberregion(optional): Region IDdistrict(optional): District IDsuburb(optional): Suburb IDpage(optional): Page numberrows(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 IDreturn_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 IDpage(optional): Page number for paginationrows(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 IDrows(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 numberpage(optional): Page numberrows(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 watchemail_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 onamount(required): The bid amount in NZDshipping_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 purchasequantity(optional): Number of items to purchase (default: 1)shipping_option(optional): Shipping option IDaccept_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 IDprice(required): The offer amount in NZDmessage(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 paginationrows(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 paginationrows(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 paginationrows(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 paginationrows(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
- Register for a Trade Me account
- Go to Developer Options
- Create a new application
- Note your Consumer Key and Consumer Secret
- 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:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
Support
For issues and questions:
- Trade Me API: Developer Documentation
- MCP Protocol: MCP Documentation
- This project: GitHub Issues