Odybook Model Context Protocol (MCP) Server

A professional-grade implementation of the Model Context Protocol (MCP) for Odybook, enabling AI assistants to interact directly with Odybook's experience management platform. This server acts as a secure proxy, providing AI tools for tour searching, availability verification, and booking management.

Overview

The Odybook MCP server allows AI models (like Claude and ChatGPT) to perform real-time operations on the Odybook platform. It implements the standard MCP Toolkit, ensuring compatibility with any MCP-compliant client.

Features

• Experience Search: Discover tours and activities by location and date.
• Real-time Availability: Verify slot capacity for specific dates and guest counts.
• Booking Management: Create temporary booking holds for customers.
• Secure Integration: Uses Odybook Partner API authentication.

Prerequisites

• Node.js 18.x or higher
• An active Odybook Partner API Key
• Odybook API URL (default: https://odybook.com/api)

Installation

1. Clone the repository and navigate to the directory:

   cd odybook-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

The server expects the following environment variables. You can define these in a .env file for development or pass them directly to the MCP client.

Variable	Description
ODYBOOK_API_KEY	(Optional) Your partner API key for protected routes like booking holds.
ODYBOOK_API_URL	The Odybook API endpoint (default: https://odybook.com/api).

Client Integration

Claude Desktop

Claude Desktop provides native support for MCP servers. To integrate Odybook:

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the following to the mcpServers object:

{
  "mcpServers": {
    "odybook": {
      "command": "node",
      "args": ["/absolute/path/to/odybook-mcp/dist/index.js"],
      "env": {
        "ODYBOOK_API_KEY": "YOUR_API_KEY_HERE",
        "ODYBOOK_API_URL": "https://odybook.com/api"
      }
    }
  }
}

3. Restart Claude Desktop.

ChatGPT (Custom GPTs)

To use Odybook with ChatGPT, you can use the Odybook backend as a Custom Action.

1. Open Specification: Use the provided OpenAPI spec at specs/openapi.json.
2. Create Action: In your Custom GPT configuration, under "Actions", click "Create new action".
3. Import Schema: Paste the content of specs/openapi.json.
4. Authentication: Select "API Key" as the authentication type and "Bearer" as the auth scheme. Paste your ODYBOOK_API_KEY.
5. Test: ChatGPT will now be able to call Odybook tools via the /api/mcp bridge.

Marketplace Submission

This server is designed to meet the requirements for official MCP registries:

• Safety Annotations: All tools include clear descriptions and follow security best practices.
• Vendor Neutrality: Implements the standard Model Context Protocol without proprietary extensions.
• Portability: Verified to run on macOS and Windows via Node.js.

Submission Links

• Claude MCP Directory Form
• GPT Store Guidelines

Tool Reference

search_tours

Search for experiences by location and date.

• Arguments:
  • location (string, optional): City or country name.
  • date (string, optional): Target date in YYYY-MM-DD format.

check_availability

Verify if an experience has enough capacity for a given date.

• Arguments:
  • experience_id (string): UUID of the experience.
  • date (string): Date in YYYY-MM-DD format.
  • time (string, optional): Specific time slot (e.g., "10:00").
  • pax (number): Number of guests.

create_booking_hold

Initiate a temporary booking hold.

• Arguments:
  • experience_id (string): UUID of the experience.
  • date (string): Target date.
  • time (string): Specific time slot (e.g., "14:00").
  • pax (number): Number of guests.
  • customer_name (string): Customer's full name.
  • customer_email (string): Customer's email address.

Development

Run the server in development mode with automatic reloading:

npm run dev

Security

This server does not store any customer data. All requests are proxied directly to the Odybook backend. Ensure your ODYBOOK_API_KEY is kept secure and never committed to version control.