A TypeScript MCP (Model Context Protocol) server for Matrix Booking API integration, enabling AI assistants to automatically check room availability and create bookings through natural language interactions.

• Room & Desk Availability: Check availability for rooms, desks, and desk banks
• Smart Booking Creation: Create bookings with attendee management and notifications
• Booking Search & Discovery: Search bookings by user, date, location, or type
• Colleague Calendar Discovery: Find when colleagues are in the office (privacy-aware)
• Booking Management: Cancel and manage existing bookings with notification options
• User Bookings: View and track your own bookings and recurring schedules

• Natural Language Search: Find locations using conversational queries
• Facility-Based Discovery: Search by requirements (screen, whiteboard, capacity)
• Location Hierarchy: Browse buildings, floors, zones, and desk banks
• Smart Location Resolution: Intelligent room/desk name and number matching
• Cross-Organization Support: Handle multiple organization contexts seamlessly

• Comprehensive Validation: Input sanitization and XSS prevention
• Smart Caching: Performance optimization with configurable TTLs
• Organization Context Resolution: Intelligent organization ID mapping with fallback
• Security-First: Environment-based credential management
• Error Recovery: Graceful degradation and alternative suggestions
• Comprehensive Testing: Unit, integration, and performance test coverage

• Node.js: ≥22.0.0
• Package Manager: npm (supported)
• Matrix Booking Account: Valid credentials required

git clone https://github.com/chrisns/matrixbookingmcp.git
cd matrixbookingmcp

Using pnpm (recommended):

pnpm install

Using npm:

npm install

Create a .env file in the project root:

cp .env.example .env

Configure the required environment variables:

# Matrix Booking Credentials
MATRIX_USERNAME=your-matrix-username
MATRIX_PASSWORD=your-matrix-password

# Default Location (optional but recommended)
MATRIX_PREFERED_LOCATION=your-preferred-location-id

pnpm build

Security Note: Never commit credentials to version control. The .env file is automatically excluded via .gitignore.

The server automatically configures:

• Base URL: https://app.matrixbooking.com/api/v1
• Authentication: HTTP Basic Auth with Base64 encoding
• Timeout: 5 seconds for all API calls
• Timezone: Europe/London (configurable via x-time-zone header)
• Headers: Required Matrix-specific headers included automatically

1. Update Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "matrix-booking": {
      "command": "npx",
      "args": ["--yes", "github:chrisns/matrixbookingmcp"],
      "env": {
        "MATRIX_USERNAME": "your-username",
        "MATRIX_PASSWORD": "your-password",
        "MATRIX_PREFERED_LOCATION": "your-location-id"
      }
    }
  }
}

Note: This will run the server directly from the GitHub repository without needing to clone or build it locally.

2. Restart Claude Desktop

The Matrix Booking tools will now be available in your Claude Desktop session.

For integration with other MCP clients, use:

• Transport: stdio
• Command: node dist/index.js
• Environment: Set the required environment variables

pnpm dev

pnpm start

// Check availability for today at preferred location
checkAvailability()

// Check availability for specific date and location  
checkAvailability({
  date: "2024-01-15",
  locationId: "12345",
  startTime: "09:00",
  endTime: "17:00"
})

// Book a room with basic details
bookAppointment({
  title: "Team Meeting",
  date: "2024-01-15", 
  startTime: "14:00",
  endTime: "15:00",
  roomId: "67890"
})

// Book with attendees and notifications
bookAppointment({
  title: "Project Review",
  date: "2024-01-15",
  startTime: "10:00", 
  endTime: "11:00",
  roomId: "67890",
  attendees: ["john@company.com", "jane@company.com"],
  sendNotifications: true
})

The server includes intelligent defaults:

• Date: Defaults to today when not specified
• Location: Uses MATRIX_PREFERED_LOCATION from environment
• Time Range: Full day (00:00-23:59) for availability checks
• Timezone: Automatically handled as Europe/London

graph TB
    A[AI Assistant/Client] --> B[MCP Server]
    B --> C[Matrix Booking API]
    
    B --> D[Configuration Manager]
    B --> E[Authentication Manager] 
    B --> F[Service Layer]
    B --> G[Input Validation]
    B --> H[Organization Context Resolver]
    
    F --> F1[Availability Service]
    F --> F2[Booking Service]
    F --> F3[Location Service]
    F --> F4[Organization Service]
    F --> F5[Search Service]
    
    H --> H1[Organization Validation]
    H --> H2[Context Resolution]
    H --> H3[Fallback Logic]
    H --> H4[Validation Cache]
    
    D --> I[Environment Variables]
    E --> J[Base64 Credentials]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style F fill:#e8f5e8
    style H fill:#ffe0e6

• MCP Server: TypeScript implementation using @modelcontextprotocol/sdk
• Authentication Manager: Secure credential handling with Base64 encoding
• Service Layer: Business logic for availability, booking, and location operations
• Organization Context Resolver: Handles organization ID mapping with fallback logic and caching
• Configuration Manager: Environment-based configuration with validation
• Input Validation: Comprehensive sanitization and validation system
• Error Handling: Pass-through error policy preserving Matrix API responses

pnpm test

pnpm test:coverage

• Unit Tests: Component and service testing
• Integration Tests: End-to-end MCP protocol testing
• Security Tests: Credential handling and validation
• Performance Tests: Load testing with K6

# Quick performance test
pnpm test:k6:quick

# Full load test
pnpm test:k6

# Timeout testing
pnpm test:k6:timeout

Symptom: 401 Unauthorized errors

Solution:

• Verify MATRIX_USERNAME and MATRIX_PASSWORD in .env
• Ensure credentials are valid for Matrix Booking
• Check for trailing spaces in environment variables

Symptom: Location not found errors

Solution:

• Verify MATRIX_PREFERED_LOCATION is a valid location ID
• Use the location service to fetch available locations
• Ensure location ID is numeric (not location name)

Symptom: Request timeout errors

Solution:

• Check network connectivity to app.matrixbooking.com
• Verify Matrix API is accessible from your network
• Consider firewall or proxy configurations

Symptom: Invalid date format errors

Solution:

• Use ISO date format: YYYY-MM-DD
• Use 24-hour time format: HH:MM
• Ensure dates are not in the past

Symptom: NaN organization ID errors or "Invalid organization context" errors

Solution:

• Verify your user account has proper organization access in Matrix Booking
• Check that MATRIX_PREFERED_LOCATION belongs to your organization
• Set MATRIX_ORGANIZATION_RESOLUTION_STRATEGY=user_preferred to prefer user's organization
• Enable cross-org access with MATRIX_ENABLE_CROSS_ORG_ACCESS=true if you need multi-org support

Symptom: get_locations returns empty arrays or booking searches fail

Solution:

• Ensure your organization has locations configured in Matrix Booking
• Verify API authentication is working correctly
• Check that your user has permissions to view locations
• Try setting a different organization resolution strategy

Symptom: "Invalid date range: End time must be after start time" for identical times

Solution:

• The system now allows identical start/end times for point-in-time queries
• Uses MATRIX_DEFAULT_DURATION_MINUTES (default: 15) to extend identical times
• For explicit ranges, ensure end time is after start time

Symptom: Tools not available in Claude Desktop

Solution:

• Verify claude_desktop_config.json syntax
• Check file path to the built server (dist/index.js)
• Ensure the project is built (pnpm build)
• Restart Claude Desktop after configuration changes

Enable detailed logging by setting:

export NODE_ENV=development

For additional support:

1. Check the troubleshooting guide
2. Review test examples in the tests/ directory
3. Open an issue on GitHub with detailed error information

The server provides 11 comprehensive tools for Matrix Booking operations:

1. check_availability - Check room/desk availability
2. book_appointment - Create new bookings with attendees
3. cancel_booking - Cancel existing bookings
4. get_user_bookings - View your bookings and schedules
5. search_bookings - Search all bookings (including colleagues)

6. get_locations - Browse location hierarchy
7. find_location_by_name - Find locations by name/number
8. find_location_by_requirements - Search by facilities and capacity
9. find_location_by_id - Get specific location details

10. get_booking_types - List available booking categories
11. get_organization_info - View organization details

For detailed parameters and examples, see the API Usage Guide

We welcome contributions! Please follow these guidelines:

1. Fork and Clone

   git fork https://github.com/chrisns/matrixbookingmcp.git
   git clone https://github.com/your-username/matrixbookingmcp.git

2. Setup Development Environment

   cd matrixbookingmcp
   pnpm install
   cp .env.example .env
   # Configure your .env file

3. Create Feature Branch

   git checkout -b feature/your-feature-name

4. Development

   pnpm dev  # Start development server
   pnpm test # Run tests in watch mode

5. Quality Checks

   pnpm lint        # Check code style
   pnpm typecheck   # Verify TypeScript
   pnpm test        # Run all tests

6. Submit Pull Request

   • Ensure all tests pass
   • Include test coverage for new features
   • Follow conventional commit messages
   • Update documentation if needed

• TypeScript: Strict mode enabled
• ESLint: Follow configured rules
• Testing: Maintain test coverage above 50%
• Commits: Use conventional commit format
• Documentation: Update for API changes

• Tests pass (pnpm test)
• Linting passes (pnpm lint)
• Type checking passes (pnpm typecheck)
• Test coverage maintained (50%+)
• Documentation updated
• Security considerations addressed

• Unit tests for all new functions
• Integration tests for API endpoints
• Security tests for credential handling
• Performance tests for critical paths

This project is licensed under the MIT License - see the LICENSE file for details.

• Project Lead: Matrix Booking MCP Server Team
• Email: maintainers@example.com
• GitHub: @chrisns/matrixbookingmcp

• ✅ Core Features: Complete
• ✅ API Integration: Stable
• ✅ Test Coverage: 54%
• ✅ Documentation: Complete
• ✅ Security: Audited
• 🔄 Performance: Continuously monitored

• Model Context Protocol for the MCP specification
• Matrix Booking for the API platform
• TypeScript and Node.js communities for excellent tooling

For more detailed information, see the technical documentation and specification documents.