Hostaway MCP Server

A FastAPI-based Model Context Protocol (MCP) server that exposes Hostaway property management operations as AI-callable tools.

Overview

This project enables AI assistants like Claude to interact with Hostaway's property management platform through standardized MCP tools. Built with FastAPI-MCP, it provides type-safe, authenticated access to listings, bookings, and guest communication.

Features

• MCP Protocol Support: Expose Hostaway API as AI-callable tools

• Type Safety: Full Pydantic model validation

• Authentication: Secure API key and OAuth2 support

• Async Performance: ASGI transport for efficient communication

• Spec-Driven Development: Integrated with Spec-Kit workflow

Quick Start

Prerequisites

• Python 3.12+

• uv or pip package manager

• Hostaway API credentials

Installation

Running the Server

Documentation

Core Documentation

• FastAPI-MCP Integration Guide - Complete guide to using FastAPI-MCP

  • Installation and setup

  • Core concepts and architecture

  • Implementation examples

  • Authentication strategies

  • Deployment options

  • Best practices and troubleshooting

• Implementation Roadmap - Project implementation plan

  • Phase-by-phase development strategy

  • Sprint timeline and milestones

  • Project structure and organization

  • Risk mitigation

  • Success criteria

Spec-Kit Workflow

This project uses Spec-Kit for spec-driven development:

1. Define Constitution: /speckit.constitution

2. Create Specification: /speckit.specify

3. Generate Plan: /speckit.plan

4. Create Tasks: /speckit.tasks

5. Implement: /speckit.implement

Project Structure

Available Tools (Planned)

Listings

• get_listing - Retrieve listing details

• list_listings - List all listings

• check_availability - Check date availability

Bookings

• search_bookings - Search with filters

• get_booking - Get booking details

• create_booking - Create new booking

Guests

• send_guest_message - Send message to guest

• get_guest - Get guest details

• get_message_history - View communication history

Development

Running Tests

Code Quality

Deployment

Docker

Docker Compose

Security

• API keys stored in environment variables

• Input validation with Pydantic

• Rate limiting enabled

• Audit logging for all tool calls

• HTTPS required in production

Contributing

1. Follow spec-driven development workflow

2. Write tests for all new features

3. Maintain >80% code coverage

4. Update documentation

5. Follow security best practices

License

MIT

Resources

• FastAPI-MCP Repository

• FastAPI-MCP Documentation

• MCP Specification

• Hostaway API Docs

• Spec-Kit

Support

For issues and questions:

• Check Documentation

• Review Troubleshooting Guide

• Open an issue on GitHub

Status: Initial Setup Complete ✅ Next Step: Begin Phase 1 - Environment Setup (see Implementation Roadmap)