MCP 服务器

mcp-goodpass-api

Enables AI assistants to interact with the GoodPass API for searching products, retrieving details, checking availability, pricing, and managing orders.

README

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)

Clone or navigate to this repository:
```
cd mcp-goodpass-api
```
Install dependencies using uv:
```
uv sync
```

Using `pip`

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

Create a .env file in the project root:
```
touch .env
```

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:

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

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.

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"
      }
    }
  }
}

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

Check Python version:
```
python --version
```
Ensure you have Python 3.12 or higher.
Verify API key: Make sure GOODPASS_API_KEY is set in your .env file or environment variables.

Check dependencies:

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

Or with uv:

uv pip list

Claude Desktop can't connect

Verify the path: Ensure the absolute path in claude_desktop_config.json is correct.
Check permissions: Make sure the script is executable:
```
chmod +x goodpass_server.py
```
Test manually: Run the server directly to check for errors:
```
python goodpass_server.py
```
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)