keithah-hostex-mcp

hostex-mcp

用于 Hostex 房源管理 API 的模型上下文协议服务。通过 Claude 和其他 MCP 客户端管理度假租赁房源、预订、住客沟通等。

基于 hostex-ts 构建，这是一个适用于 Hostex API v3.0.0 的 TypeScript 客户端库。

功能

• 🏠 房源 - 房源和房型管理
• 📅 预订 - CRUD 操作、自定义字段、门锁密码
• 📊 可订状态 - 房源可订日历
• 📋 房源列表 - 渠道房源、定价、库存
• 💬 消息 - 与住客沟通和发送消息
• ⭐ 评价 - 评价管理与回复
• 🔗 Webhooks - 实时事件通知
• ⚙️ 实用工具 - 自定义渠道和收入方式

可用工具（25+）

• hostex_list_properties - 列出所有房源
• hostex_list_room_types - 列出房型
• hostex_list_reservations - 搜索和筛选预订
• hostex_create_reservation - 创建直接预订
• hostex_cancel_reservation - 取消预订
• hostex_update_lock_code - 更新入住期间的门锁密码
• hostex_get_custom_fields - 获取自定义字段值
• hostex_update_custom_fields - 更新自定义字段
• hostex_list_availabilities - 查看房源可订状态
• hostex_update_availabilities - 封锁或开放日期
• hostex_list_conversations - 列出与住客的对话
• hostex_get_conversation - 获取对话详情
• hostex_send_message - 向住客发送消息
• hostex_list_reviews - 查询评价
• hostex_create_review - 留下评价或回复
• hostex_list_webhooks - 列出已配置的 Webhook
• hostex_create_webhook - 注册新 Webhook
• hostex_delete_webhook - 移除 Webhook
• hostex_get_listing_calendar - 获取房源日历
• hostex_update_listing_prices - 更新渠道价格
• hostex_list_custom_channels - 列出自定义渠道
• hostex_list_income_methods - 列出收入方式

安装

选项 1：通过 Smithery（推荐）

直接从 Smithery 安装：

npx -y @smithery/cli install @keithah/hostex-mcp --client claude

或者将托管服务 URL 添加到你的 MCP 客户端：

https://server.smithery.ai/@keithah/hostex-mcp/mcp

系统提示时，请提供你的 Hostex API 访问令牌。

选项 2：MCPB 包

1. 从 Releases 下载最新的 .mcpb 文件
2. 双击该文件，在 MCP 客户端中安装
3. 系统提示时，配置你的 Hostex API 令牌

选项 3：手动安装（Claude Desktop）

添加到你的 Claude Desktop 配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Linux 上为 ~/.config/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "hostex": {
      "command": "npx",
      "args": ["-y", "hostex-mcp"],
      "env": {
        "HOSTEX_ACCESS_TOKEN": "your_hostex_api_token"
      }
    }
  }
}

或者使用 Smithery 托管服务：

{
  "mcpServers": {
    "hostex": {
      "url": "https://server.smithery.ai/@keithah/hostex-mcp/mcp",
      "env": {
        "HOSTEX_ACCESS_TOKEN": "your_hostex_api_token"
      }
    }
  }
}

配置

你需要 Hostex API 访问令牌。请前往 https://www.hostex.io/ 的 Hostex 账户设置获取令牌。

服务接受通过 configSchema 传入的配置：

• accessToken（必填）：你的 Hostex API 访问令牌

使用示例

安装后，你可以用自然语言向 Claude 提问，例如：

• “显示我的所有 Hostex 房源”
• “列出本周入住的预订”
• “将房源 12345 下周末设为不可订”
• “向对话 ABC123 中的住客发送欢迎消息”
• “我这个月收到了哪些评价？”
• “为房源 XYZ 创建直接预订”

开发

前置条件

• Node.js >= 18
• npm

设置

# Clone the repository
git clone https://github.com/keithah/hostex-mcp.git
cd hostex-mcp

# Install dependencies
npm install

# Build for stdio transport
npm run build:stdio

# Build for streamable HTTP transport
npm run build:shttp

# Build both transports
npm run build:all

本地测试

# Start dev server with Smithery
npm run dev

架构

此 MCP 服务使用：

• @modelcontextprotocol/sdk - MCP 协议实现
• @smithery/sdk - 多传输支持
• hostex-ts - Hostex API 客户端库
• zod - 架构验证

传输方式

该服务支持两种传输协议：

• stdio - 标准输入/输出（适用于 Claude Desktop 等本地 MCP 客户端）
• shttp - 流式 HTTP（适用于远程或基于 Web 的 MCP 客户端）

两者均使用 Smithery 构建，以实现无缝的多传输支持。

自动更新

此仓库包含一个 GitHub Actions 工作流，用于：

1. 每小时检查 npm 上 hostex-ts 是否有新版本
2. 自动创建 PR 以更新依赖项
3. 更新补丁版本号
4. 重新构建 MCP 包

合并 PR 并创建新的发布标签后，MCPB 包会自动构建并附加到 GitHub 发布中。

要求

• Node.js >= 18
• 兼容 MCP 的客户端（Claude Desktop v0.10.0+，或任何 MCP 客户端）
• 可访问 API 的 Hostex 账户

文档

• Hostex API 文档
• hostex-ts npm 包
• Model Context Protocol

许可证

MIT

作者

Keith Hadfield

支持

• 问题反馈：GitHub Issues
• Hostex API：https://docs.hostex.io/
• MCP 文档：https://modelcontextprotocol.io/

---

注意：这是一个非官方的社区项目，Hostex 不提供官方支持。