officernd-mcp-server/README.md

MCP server for OfficeRnD workspace management - create, search, update and cancel bookings

# OfficeRnD MCP Server

A Model Context Protocol (MCP) server for OfficeRnD workspace management. This server enables Claude and other MCP-compatible AI assistants to interact with OfficeRnD APIs to manage bookings, resources, members, and companies.

## Features

- 🏢 **Booking Management**: Create, update, search, and cancel bookings
- 🏠 **Resource Management**: Search meeting rooms, desks, and event spaces
- 👥 **Member & Company Management**: Search and manage workspace members and companies
- 💰 **Pricing Information**: Access resource rates and pricing data
- 🌍 **Timezone Support**: Automatic timezone handling for global workspaces
- 🔒 **Secure Authentication**: OAuth 2.0 client credentials flow

## Quick Start

### Using npx (Recommended)

No installation required! Just configure and run:

```bash
npx officernd-mcp-server
```

### Installation

```bash
npm install -g officernd-mcp-server
```

## Configuration

### 1. Get OfficeRnD API Credentials

1. Log into your OfficeRnD admin panel
2. Go to Settings → Integrations → API
3. Create new OAuth application
4. Copy the Client ID and Client Secret

### 2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "officernd": {
      "command": "npx",
      "args": ["officernd-mcp-server"],
      "env": {
        "OFFICERND_CLIENT_ID": "your_client_id_here",
        "OFFICERND_CLIENT_SECRET": "your_client_secret_here", 
        "OFFICERND_ORG_SLUG": "your_organization_slug"
      }
    }
  }
}
```

### Advanced Configuration (Optional)

For performance tuning and default settings, you can add these optional environment variables:

```json
{
  "mcpServers": {
    "officernd": {
      "command": "npx",
      "args": ["officernd-mcp-server"],
      "env": {
        "OFFICERND_CLIENT_ID": "your_client_id_here",
        "OFFICERND_CLIENT_SECRET": "your_client_secret_here", 
        "OFFICERND_ORG_SLUG": "your_organization_slug",
        "RESOURCE_CACHE_MINUTES": "60",
        "OFFICERND_DEFAULT_COMPANY_ID": "601a491e515797fd9575bc1a"
      }
    }
  }
}
```

**Advanced Settings:**
- `RESOURCE_CACHE_MINUTES`: How long to cache resource data (default: 60 minutes)
- `OFFICERND_DEFAULT_COMPANY_ID`: Default company ID for bookings - when creating bookings without specifying a company, this ID will be used automatically

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server with your credentials.

## Usage Examples

### Create a Booking

```
Create a booking for the main conference room tomorrow from 2 PM to 4 PM for Acme Corp.
```

If you have configured a default company ID, you can simply say:
```
Book the event space next Tuesday from 10 AM to 12 PM
```

### Search Bookings

```
Show me all bookings for the event space this week.
```

### Cancel a Booking

```
Cancel booking BB7H96Z
```

### Find Available Resources

```
What meeting rooms are available that can seat 10 people?
```

## Important: Timezone Handling

⚠️ **All times must be provided in UTC format**

When creating or searching for bookings, convert your local time to UTC:

- **Zurich CEST (Summer)**: Subtract 2 hours  
  - Local 2:00 PM → UTC 12:00 PM → `2025-06-17T12:00:00.000Z`
- **Zurich CET (Winter)**: Subtract 1 hour  
  - Local 2:00 PM → UTC 1:00 PM → `2025-01-17T13:00:00.000Z`

## Important: Response Handling Guidelines

⚠️ **Only use data directly from API responses**

When using this MCP server, AI assistants must:

- **Never make assumptions** about company names, organizations, or any other data not explicitly returned by the API
- **Only respond based on evidence** from the actual API data
- **Never guess or infer** information that isn't directly present in the response
- **Ask for clarification** if information is ambiguous rather than making assumptions

For example, if a booking shows a company ID but not the company name, do not assume or guess the company name - only refer to it by its ID or fetch the company details using the appropriate tool.

## Important: Administrator Access

⚠️ **This MCP server operates with administrator privileges**

When using this MCP server:

- **The user has full administrative access** to the OfficeRnD platform through the API
- **No additional authorization is required** for any operations - the API credentials provide platform-wide access
- **The user is acting as an administrator**, not as a regular member
- **All actions are performed at the platform level**, not restricted to a specific member or company

This means you can manage all bookings, resources, members, and companies across the entire workspace without needing to check permissions for individual operations.

## Available Tools

### Booking Management
- `create_booking` - Create new bookings
- `update_booking` - Modify existing bookings  
- `cancel_booking` - Cancel bookings
- `search_bookings` - Find bookings with filters
- `get_booking_details` - Get detailed booking information

### Resource Management
- `search_resources` - Find meeting rooms, desks, etc.
- `get_resource_details` - Get detailed resource information
- `get_resource_types` - List available resource categories
- `get_bookable_resources_with_rates` - Resources with pricing

### Member & Company Management
- `search_members` - Find workspace members
- `search_companies` - Find companies  
- `get_member_details` - Detailed member information
- `get_company_details` - Detailed company information

### Pricing & Rates
- `search_resource_rates` - Find pricing information
- `get_rates_for_resource` - Get rates for specific resources

## Development

### Local Development

```bash
git clone https://github.com/Trust-Square/officernd-mcp-server.git
cd officernd-mcp-server
npm install
npm run build
npm start
```

### Environment Variables

In development mode, you can either:

1. Create a `.env` file:
```env
OFFICERND_CLIENT_ID=your_client_id
OFFICERND_CLIENT_SECRET=your_client_secret
OFFICERND_ORG_SLUG=your_org_slug
RESOURCE_CACHE_MINUTES=60
OFFICERND_DEFAULT_COMPANY_ID=your_default_company_id
```

2. Or use the `configure_officernd` tool (only available in development mode):
```
Please configure OfficeRnD with:
- Client ID: your_client_id
- Client Secret: your_client_secret  
- Organization Slug: your_org_name
```

## Troubleshooting

### Common Issues

**"OfficeRnD not configured" error**
- Ensure your API credentials are correct
- Check that your organization slug matches your OfficeRnD account

**Timezone confusion**  
- Remember to convert local time to UTC
- Use the format: `YYYY-MM-DDTHH:MM:SS.000Z`

**"Booking not found" when cancelling**
- Verify the booking ID is correct
- Check that the booking hasn't already been cancelled

### Getting Help

1. Check the [OfficeRnD API Documentation](https://developers.officernd.com/)
2. Review your API credentials and permissions
3. Ensure your OfficeRnD subscription includes API access

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OfficeRnD](https://www.officernd.com/)
- [Claude Desktop](https://claude.ai/desktop)