aigohotel-mcp 0.1.0

MCP server for global hotel search powered by AIGOHOTEL API

AigoHotel MCP Server (UV Version)

AIGOHOTEL 酒店搜索 MCP Server。通过标准的 Model Context Protocol (MCP) 协议为 AI 助手提供全球酒店搜索能力。

本项目使用 uv 进行依赖管理和环境隔离。

项目结构

aigohotel-mcp-uv/
├── README.md
├── pyproject.toml
├── server.py
├── aigohotel_mcp/
│   ├── __init__.py
│   └── server.py
└── uv.lock

工具列表

search_hotels - 查询全球酒店信息

• 支持按城市、景点、酒店、交通枢纽等多种地点类型搜索
• 支持星级筛选、距离筛选、入住日期等多维度条件
• 返回符合条件的酒店列表(JSON格式)

请求参数

必填参数:

• place (string): 目的地(城市、景点、酒店、交通枢纽、地标等)
• placeType (string): 目的地类型(城市、区/县、机场、火车站、酒店、景点等)

可选参数:

• originalQuery (string): 用户的原始问询句
• checkIn (string): 入住日期,格式 yyyy-MM-dd,默认次日
• stayNights (int): 入住晚数,默认 1
• starRatings (array): 酒店星级范围,如 [4.5, 5.0],默认 [0.0, 5.0]
• adultCount (int): 每间房成人数量,默认 2
• distanceInMeter (int): 距离景点的米数,默认 5000
• size (int): 返回结果数量,默认 10,最大 20
• withHotelAmenities (bool): 是否包含酒店设施,默认 true
• withRoomAmenities (bool): 是否包含客房设施,默认 true
• language (string): 语言环境(zh_CN, en_US等),默认 zh_CN
• queryParsing (bool): 是否分析用户个性化需求,默认 true

使用示例

示例 1: 搜索西雅图的酒店

{
  "place": "西雅图",
  "placeType": "城市"
}

示例 2: 搜索白金汉宫附近的高星级酒店

{
  "place": "白金汉宫",
  "placeType": "景点",
  "checkIn": "2026-01-01",
  "starRatings": [4.5, 5.0]
}

快速开始

1. 初始化项目

# 进入项目目录
cd aigohotel-mcp-uv

# 初始化 uv 项目(如果是新克隆的项目)
uv init

# 创建虚拟环境
uv venv

# 激活虚拟环境
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# Windows CMD:
.venv\Scripts\activate.bat
# Linux/Mac:
source .venv/bin/activate

# 安装依赖
uv add fastmcp httpx

2. 配置 API Key (必需)

获取 API Key: https://mcp.agentichotel.cn/apply

设置环境变量:

# Windows PowerShell:
$env:AIGOHOTEL_API_KEY="mcp_your_actual_api_key_here"

# Windows CMD:
set AIGOHOTEL_API_KEY=mcp_your_actual_api_key_here

# Linux/Mac:
export AIGOHOTEL_API_KEY=mcp_your_actual_api_key_here

重要:

• 前往 https://mcp.agentichotel.cn/apply 申请 API Key
• API Key 必须以 mcp_ 开头
• 未配置或格式错误将导致 API 请求失败

3. 启动服务器

# 方式1: 直接运行
python server.py

# 方式2: 使用 uvx 启动
uvx aigohotel_mcp

# 方式3: 使用 uv run
uv run python server.py

启动成功后会显示:

INFO: Uvicorn running on http://127.0.0.1:8000

如果 API Key 格式错误,会显示警告:

警告: API Key 格式错误,应以 'mcp_' 开头

MCP 客户端配置

方式1: UVX 命令行模式 (推荐)

在 MCP 客户端配置文件中添加:

Claude Desktop (Windows): 配置文件路径: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "aigohotel": {
      "command": "uvx",
      "args": [
        "--from",
        "e:/Cursor/测试脚本File/aigohotel-mcp-uv",
        "aigohotel_mcp"
      ],
      "env": {
        "AIGOHOTEL_API_KEY": "mcp_your_actual_api_key_here"
      }
    }
  }
}

Claude Desktop (Mac/Linux): 配置文件路径: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aigohotel": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/aigohotel-mcp-uv",
        "aigohotel_mcp"
      ],
      "env": {
        "AIGOHOTEL_API_KEY": "mcp_your_actual_api_key_here"
      }
    }
  }
}

Cline/其他 MCP 客户端:

{
  "mcpServers": {
    "aigohotel": {
      "command": "uvx",
      "args": ["--from", "e:/Cursor/测试脚本File/aigohotel-mcp-uv", "aigohotel_mcp"],
      "env": {
        "AIGOHOTEL_API_KEY": "mcp_your_actual_api_key_here"
      }
    }
  }
}

方式2: HTTP 服务模式

先手动启动服务:

cd aigohotel-mcp-uv
python server.py

然后在 MCP 配置文件中添加:

{
  "mcpServers": {
    "aigohotel": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

配置说明

• command: 使用 uvx 命令启动
• args:
  • --from: 指定项目路径(绝对路径)
  • aigohotel_mcp: 项目入口脚本名称(在 pyproject.toml 中定义)
• env: 环境变量配置
  • AIGOHOTEL_API_KEY: 必须配置,从 https://mcp.agentichotel.cn/apply 获取

开发指南

安装开发依赖

uv add --dev pytest pytest-asyncio

运行测试

uv run pytest

API 鉴权说明

访问 https://mcp.agentichotel.cn/apply 申请 API Key

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

相关链接

• Model Context Protocol
• FastMCP
• UV Package Manager
• API Key 申请