MCP Goodpass API

MCP GoodPass API服务器

模型上下文协议（MCP）服务器，提供对GoodPass API的访问，允许人工智能助手搜索产品、检索产品详细信息、检查可用性、获取定价和管理订单。

概述

该MCP服务器通过标准化界面公开GoodPass API，使Claude Desktop等人工智能助手能够与GoodPass服务交互。服务器提供以下工具：

• 使用筛选器搜索产品
• 正在检索产品详细信息
• 检查可用日期
• 获取定价信息
• 创建临时订单
• 检索订单

先决条件

• Python 3.12或更高版本
• uv 包管理器（推荐）或 pip
• GoodPass API密钥

安装

使用 uv （推荐）

1. 克隆或导航到此存储库：

   cd mcp-goodpass-api

1. 使用安装依赖项 uv:

   uv sync

使用 pip

1. 安装依赖项：

   pip install -e .

或直接安装：

   pip install httpx mcp[cli] python-dotenv requests

配置

环境变量

创建一个 .env 项目根目录中的文件，包含以下变量：

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

必修的：

• GOODPASS_API_KEY：您的GoodPass API密钥（必需）

可选：

• GOODPASS_BASE_URL：GoodPass API的基本URL（默认为 https://partner-api.goodpass.club/v1)

创建 .env 文件

1. 创建一个 .env 项目根目录中的文件：

   touch .env

1. 添加您的配置：

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

运行服务器

直接执行

直接运行服务器：

python goodpass_server.py

或使用 uv:

uv run goodpass_server.py

服务器通过stdio（标准输入/输出）运行，这是MCP服务器的标准传输方式。

MCP检验员测试

您可以使用MCP检查器测试服务器。打开 MCP Inspector.html 在浏览器中与服务器交互。

在Claude Desktop中配置

要将此MCP服务器与Claude Desktop一起使用：

1. 找到Claude Desktop配置文件：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. 编辑配置文件 并添加MCP服务器：

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

注： 替换 /absolute/path/to/mcp-goodpass-api/goodpass_server.py 与您的实际绝对路径 goodpass_server.py 文件。

1. 替代使用 uv:

如果你正在使用 uv，您可以这样配置它：

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

1. 重新启动克劳德桌面 以使更改生效。

可用工具

MCP服务器提供以下工具：

find_products

使用过滤器搜索产品。

参数：

• page （int，默认值：1）：页码
• limit （int，默认值：10）：每页结果
• categories （List\[str\]，可选）：按类别筛选
• themes （List\[str\]，可选）：按主题筛选
• destination （str，可选）：按目的地筛选
• search （str，可选）：搜索查询
• minPrice （浮动，可选）：最低价格过滤器
• maxPrice （浮动，可选）：最大价格过滤器
• productType （str，可选）：按产品类型筛选
• currency （str，可选）：货币代码

retrieve_product

按ID检索单个产品。

参数：

• id （str，必填）：产品ID

get_available_dates

列出产品的可用日期。

参数：

• id （str，必填）：产品ID

get_prices_for_date

获取特定日期的产品定价。

参数：

• id （str，必填）：产品ID
• date （str，必填）：YYYY-MM-DD格式的日期

create_temp_order

创建临时订单。

参数：

• productId （str，必填）：产品ID
• date （str，必填）：YYYY-MM-DD格式的日期
• ticketSelections （Dict\[str，int\]，必填）：票选择映射
• usercode （str，必填）：用户代码

get_order_forms

检索订单所需的表单字段。

参数：

• orderId （str，必填）：订单ID

故障排除

服务器无法启动

1. 检查Python版本：

   python --version

确保你有Python 3.12或更高版本。

1. 验证API密钥：

确保 GOODPASS_API_KEY 设置在您的 .env 文件或环境变量。

1. 检查依赖关系：

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

或与 uv:

   uv pip list

Claude Desktop无法连接

1. 验证路径：

确保绝对路径 claude_desktop_config.json 是正确的。

1. 检查权限：

确保脚本可执行：

   chmod +x goodpass_server.py

1. 手动测试：

直接运行服务器以检查错误：

   python goodpass_server.py

1. 检查日志：

Claude Desktop日志可能包含错误消息。检查控制台或日志文件。

API错误

• 验证您的API密钥是否有效并具有必要的权限
• 检查 GOODPASS_BASE_URL 是正确的
• 确保您的网络连接正常工作
• 查看API响应中的特定错误消息

发展

项目结构

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)

添加新工具

要向MCP服务器添加新工具，请执行以下操作：

1. 添加一个新功能，用 @mcp.tool() 在 goodpass_server.py
2. 使用 _get() 或 _post() API调用的助手函数
3. 用docstring记录函数
4. 重新启动服务器以加载新工具

许可证

\[在此处添加您的许可证信息\]

支持

关于以下问题：

• MCP服务器：在此存储库中打开一个问题
• GoodPass API：联系GoodPass支持
• 克劳德桌面：查看Claude Desktop文档