MCP GoodPass API Server

A Model Context Protocol (MCP) server that provides access to the GoodPass API, allowing AI assistants to search for products, retrieve product details, check availability, get pricing, and manage orders.

Overview

This MCP server exposes the GoodPass API through a standardized interface, enabling AI assistants like Claude Desktop to interact with GoodPass services. The server provides tools for:

• Searching products with filters
• Retrieving product details
• Checking available dates
• Getting pricing information
• Creating temporary orders
• Retrieving order forms

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended) or pip
• A GoodPass API key

Installation

Using uv (Recommended)

1. Clone or navigate to this repository:

   cd mcp-goodpass-api
   

2. Install dependencies using uv:

   uv sync
   

Using pip

1. Install dependencies:

   pip install -e .
   

   Or install directly:

   pip install httpx mcp[cli] python-dotenv requests
   

Configuration

Environment Variables

Create a .env file in the project root directory with the following variables:

GOODPASS_API_KEY=your_api_key_here
GOODPASS_BASE_URL=https://partner-api.goodpass.club/v1

Required:

• GOODPASS_API_KEY: Your GoodPass API key (required)

Optional:

• GOODPASS_BASE_URL: The base URL for the GoodPass API (defaults to https://partner-api.goodpass.club/v1)

Creating the .env file

1. Create a .env file in the project root:

   touch .env
   

2. Add your configuration:

   echo "GOODPASS_API_KEY=your_actual_api_key" >> .env
   echo "GOODPASS_BASE_URL=https://partner-api.goodpass.club/v1" >> .env
   

Running the Server

Direct Execution

Run the server directly:

python goodpass_server.py

Or using uv:

uv run goodpass_server.py

The server runs over stdio (standard input/output), which is the standard transport for MCP servers.

Testing with MCP Inspector

You can test the server using the MCP Inspector. Open MCP Inspector.html in your browser to interact with the server.

Configuring in Claude Desktop

To use this MCP server with Claude Desktop:

1. Locate Claude Desktop configuration file:

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

2. Edit the configuration file and add the MCP server:

   {
     "mcpServers": {
       "mcp-goodpass-api": {
         "command": "python",
         "args": [
           "/absolute/path/to/mcp-goodpass-api/goodpass_server.py"
         ],
         "env": {
           "GOODPASS_API_KEY": "your_api_key_here",
           "GOODPASS_BASE_URL": "https://partner-api.goodpass.club/v1"
         }
       }
     }
   }
   

   Note: Replace /absolute/path/to/mcp-goodpass-api/goodpass_server.py with the actual absolute path to your goodpass_server.py file.

3. Alternative using uv: If you're using uv, you can configure it like this:

   {
     "mcpServers": {
       "mcp-goodpass-api": {
         "command": "uv",
         "args": [
           "run",
           "/absolute/path/to/mcp-goodpass-api/goodpass_server.py"
         ],
         "env": {
           "GOODPASS_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

4. Restart Claude Desktop for the changes to take effect.

Available Tools

The MCP server provides the following tools:

find_products

Search products with filters.

Parameters:

• page (int, default: 1): Page number
• limit (int, default: 10): Results per page
• categories (List[str], optional): Filter by categories
• themes (List[str], optional): Filter by themes
• destination (str, optional): Filter by destination
• search (str, optional): Search query
• minPrice (float, optional): Minimum price filter
• maxPrice (float, optional): Maximum price filter
• productType (str, optional): Filter by product type
• currency (str, optional): Currency code

retrieve_product

Retrieve a single product by ID.

Parameters:

• id (str, required): Product ID

get_available_dates

List available dates for a product.

Parameters:

• id (str, required): Product ID

get_prices_for_date

Get pricing for a product on a specific date.

Parameters:

• id (str, required): Product ID
• date (str, required): Date in YYYY-MM-DD format

create_temp_order

Create a temporary order.

Parameters:

• productId (str, required): Product ID
• date (str, required): Date in YYYY-MM-DD format
• ticketSelections (Dict[str, int], required): Ticket selections mapping
• usercode (str, required): User code

get_order_forms

Retrieve required form fields for an order.

Parameters:

• orderId (str, required): Order ID

Troubleshooting

Server won't start

1. Check Python version:

   python --version
   

   Ensure you have Python 3.12 or higher.

2. Verify API key: Make sure GOODPASS_API_KEY is set in your .env file or environment variables.

3. Check dependencies:

   pip list | grep -E "httpx|mcp|dotenv"
   

   Or with uv:

   uv pip list
   

Claude Desktop can't connect

1. Verify the path: Ensure the absolute path in claude_desktop_config.json is correct.

2. Check permissions: Make sure the script is executable:

   chmod +x goodpass_server.py
   

3. Test manually: Run the server directly to check for errors:

   python goodpass_server.py
   

4. Check logs: Claude Desktop logs may contain error messages. Check the console or log files.

API errors

• Verify your API key is valid and has the necessary permissions
• Check the GOODPASS_BASE_URL is correct
• Ensure your network connection is working
• Review the API response for specific error messages

Development

Project Structure

mcp-goodpass-api/
├── goodpass_server.py    # Main MCP server implementation
├── main.py               # Entry point (optional)
├── pyproject.toml        # Project dependencies
├── README.md             # This file
└── .env                  # Environment variables (create this)

Adding New Tools

To add new tools to the MCP server:

1. Add a new function decorated with @mcp.tool() in goodpass_server.py
2. Use the _get() or _post() helper functions for API calls
3. Document the function with a docstring
4. Restart the server to load the new tool

License

[Add your license information here]

Support

For issues related to:

• MCP Server: Open an issue in this repository
• GoodPass API: Contact GoodPass support
• Claude Desktop: Check Claude Desktop documentation