Manages Trade Me API credentials and configuration through environment variables for secure authentication setup
Version control system for managing the Trade Me MCP server codebase and development workflow
Hosts the repository and issue tracking for the Trade Me MCP server project
Supports Claude Desktop integration on macOS through specific configuration file paths for Trade Me marketplace access
Provides testing framework for validating Trade Me MCP server functionality and API integration reliability
Implements the MCP server using Python 3.11+ with tools for Trade Me marketplace integration including OAuth authentication, search capabilities, and transaction management
Comprehensive documentation covering installation, configuration, and usage of all Trade Me marketplace integration features
Ensures code quality and linting for the Trade Me MCP server implementation
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:
Create a virtual environment:
Install dependencies:
Configure environment variables:
Environment Variables
Usage
Running the 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
Other MCP Clients
The server uses standard MCP protocol over stdio. Configure your client to run:
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:
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:
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:
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:
get_legal_notice
Get legal notice text for a category.
Parameters:
category_number
(required): Trade Me category number
Example:
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_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:
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:
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:
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:
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_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:
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:
get_listing_photos
Get all photos for a listing in various sizes.
Parameters:
listing_id
(required): The Trade Me listing ID
Example:
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:
get_bidding_history
Get the bidding history for an auction listing.
Parameters:
listing_id
(required): The Trade Me listing ID
Example:
get_shipping_options
Get available shipping methods and costs.
Parameters:
listing_id
(required): The Trade Me listing ID
Example:
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:
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:
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:
remove_from_watchlist
Remove a listing from the authenticated user's watchlist.
Parameters:
listing_id
(required): The Trade Me listing ID to unwatch
Example:
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:
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:
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:
withdraw_offer
Withdraw a previously made fixed price offer.
Parameters:
offer_id
(required): The offer ID to withdraw
Example:
accept_offer
Accept an offer made on your listing (seller action).
Parameters:
offer_id
(required): The offer ID to accept
Example:
decline_offer
Decline an offer made on your listing (seller action).
Parameters:
offer_id
(required): The offer ID to decline
Example:
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:
get_won_items
Get auctions the authenticated user has won.
Parameters:
page
(optional): Page number for paginationrows
(optional): Results per page (max 500)
Example:
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:
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:
Development
Running Tests
Code Quality
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
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
This server cannot be installed
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.