AI导哈

GoodPass API服务

一个提供GoodPass API访问的MCP服务器，允许AI助手搜索产品、获取产品详情、检查可用性、获取价格和管理订单。

  • by eshwar-chandra
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 eshwar-chandra/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

  2. 使用安装依赖项 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

  2. 添加您的配置：

    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

  2. 编辑配置文件 并添加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 文件。

  3. 替代使用 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"
      }
    }
  }
}

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

可用工具

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或更高版本。

  2. 验证API密钥： 确保 GOODPASS_API_KEY 设置在您的 .env 文件或环境变量。

  3. 检查依赖关系：

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

    或与 uv:

    uv pip list

Claude Desktop无法连接

  1. 验证路径： 确保绝对路径 claude_desktop_config.json 是正确的。

  2. 检查权限： 确保脚本可执行：

    chmod +x goodpass_server.py

  3. 手动测试： 直接运行服务器以检查错误：

    python goodpass_server.py

  4. 检查日志： 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文档

相关 MCP