luthersystems/mcp-server-buildium

Buildium MCP Server

Experimental Model Context Protocol (MCP) server for Buildium Property Management API, built with Python + FastMCP. Uses API key authentication for server-to-server communication.

⚠️ Status & Disclaimers

• Experimental: Not production-ready; no SLA; APIs and behavior may change.
• No affiliation with Buildium: This is a community integration. Buildium is a trademark of Buildium, LLC.
• Security: Do not commit secrets. Treat client IDs and secrets as sensitive; use a secrets manager. Use at your own risk.

Features

• 🔐 API Key Authentication - Secure server-to-server authentication via headers
• 🏘️ 81 Tools Across 12 Categories - Comprehensive property management coverage
• 📋 Selective Tool Loading - Enable only the categories you need
• 🏢 Multi-Property Types - Rentals, associations, and units
• 🔌 MCP Protocol - Compatible with Claude Desktop, Cursor, and other MCP clients

Requirements

• Python 3.11+
• uv package manager (or pip)
• Buildium API credentials (client ID and client secret)

Installation

Using uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the package
uv pip install -e "git+https://github.com/luthersystems/mcp-server-buildium.git"

Using pip

pip install git+https://github.com/luthersystems/mcp-server-buildium.git

Configuration

Configure the server using environment variables:

# API Base URL (no /v1 suffix - SDK adds it automatically)
BUILDIUM_BASE_URL=https://api.buildium.com  # Production
# BUILDIUM_BASE_URL=https://apisandbox.buildium.com  # Sandbox

# API Key Credentials
BUILDIUM_CLIENT_ID=your-client-id
BUILDIUM_CLIENT_SECRET=your-client-secret

# Optional: Selective Tool Categories (comma-separated)
# If not specified, all categories are enabled
BUILDIUM_CATEGORIES=associations,leases,rentals

Tool Categories

Control which tool categories are enabled using the BUILDIUM_CATEGORIES environment variable:

Total: 81 tools

If BUILDIUM_CATEGORIES is not set, all 81 tools across all 12 categories are enabled.

Environment File

Create a .env file (copy from .env.example):

cp .env.example .env
# Edit .env with your credentials

Usage

Running the Server

# With uv
uv run mcp-server-buildium

# Or with Python
python -m mcp_server_buildium.server

Using with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "buildium": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/luthersystems/mcp-server-buildium",
        "mcp-server-buildium"
      ],
      "env": {
        "BUILDIUM_BASE_URL": "https://apisandbox.buildium.com/",
        "BUILDIUM_CLIENT_ID": "your-client-id",
        "BUILDIUM_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Available Tools (81 total)

Associations (6 tools)

• list_associations - List all associations
• get_association - Get association details by ID
• create_association - Create a new association
• update_association - Update an existing association
• list_association_board_members - List board members for an association
• list_association_ownership_accounts - List ownership accounts for an association

Leases (5 tools)

• list_leases - List leases with optional filters
• get_lease - Get lease details by ID
• create_lease - Create a new lease
• update_lease - Update an existing lease
• list_lease_transactions - List transactions for a lease

Rentals (5 tools)

• list_rentals - List rental properties
• get_rental - Get rental property details by ID
• create_rental - Create a new rental property
• update_rental - Update an existing rental property
• list_unit_listings - List unit listings for rentals

Applicants (10 tools)

• list_applicants - List rental applicants
• get_applicant - Get applicant details by ID
• create_applicant - Create a new applicant
• update_applicant - Update an existing applicant
• list_applicant_applications - List applications for an applicant
• get_application - Get application details by ID
• update_application - Update an application
• list_applicant_groups - List applicant groups
• create_applicant_group - Create a new applicant group
• update_applicant_group - Update an applicant group

Tenants (7 tools)

• list_rental_tenants - List rental tenants
• get_rental_tenant - Get rental tenant details by ID
• create_rental_tenant - Create a new rental tenant
• update_rental_tenant - Update a rental tenant
• list_association_tenants - List association tenants
• create_association_tenant - Create a new association tenant
• update_association_tenant - Update an association tenant

Owners (8 tools)

• list_rental_owners - List rental property owners
• get_rental_owner - Get rental owner details by ID
• create_rental_owner - Create a new rental owner
• update_rental_owner - Update a rental owner
• list_association_owners - List association owners
• get_association_owner - Get association owner details by ID
• create_association_owner - Create a new association owner
• update_association_owner - Update an association owner

Units (7 tools)

• list_rental_units - List rental units
• get_rental_unit - Get rental unit details by ID
• create_rental_unit - Create a new rental unit
• update_rental_unit - Update a rental unit
• list_association_units - List association units
• create_association_unit - Create a new association unit
• update_association_unit - Update an association unit

Vendors (7 tools)

• list_vendors - List vendors
• get_vendor - Get vendor details by ID
• create_vendor - Create a new vendor
• update_vendor - Update an existing vendor
• list_vendor_categories - List vendor categories
• create_vendor_category - Create a new vendor category
• update_vendor_category - Update a vendor category

Tasks (5 tools)

• list_tasks - List tasks
• get_task - Get task details by ID
• list_task_categories - List task categories
• create_task_category - Create a new task category
• update_task_category - Update a task category

Bills (7 tools)

• list_bills - List bills
• get_bill - Get bill details by ID
• create_bill - Create a new bill
• update_bill - Update an existing bill
• list_bill_payments - List payments for bills
• get_bill_payment - Get bill payment details by ID
• create_bill_payment - Create a new bill payment

Files (8 tools)

• list_files - List files
• get_file - Get file details by ID
• update_file - Update file metadata
• create_file_upload_request - Create a file upload request
• create_file_download_request - Create a file download request
• list_file_categories - List file categories
• create_file_category - Create a new file category
• update_file_category - Update a file category

Bank Accounts (6 tools)

• list_bank_accounts - List bank accounts
• get_bank_account - Get bank account details by ID
• create_bank_account - Create a new bank account
• update_bank_account - Update a bank account
• list_bank_account_transactions - List transactions for a bank account
• get_bank_account_transaction - Get bank account transaction details by ID

Tool Request/Response Examples

This section provides detailed schemas and examples for key MCP tools.

Example: List Leases

Query leases with optional filters (property, unit, status).

Parameters:

• property_id (int, optional): Filter by property ID
• unit_id (int, optional): Filter by unit ID
• lease_status (str, optional): Filter by status (e.g., "Active", "Future", "Past", "Expired")
• limit (int, optional): Maximum results (default: 100)
• offset (int, optional): Pagination offset (default: 0)

Example Request (no filters):

{
  "name": "list_leases",
  "arguments": {}
}

Example Request (with filters):

{
  "name": "list_leases",
  "arguments": {
    "property_id": 123,
    "lease_status": "Active",
    "limit": 50
  }
}

Example Response:

{
  "leases": [
    {
      "id": 12345,
      "propertyId": 123,
      "unitId": 456,
      "leaseType": "Fixed",
      "leaseFromDate": "2024-01-01",
      "leaseToDate": "2024-12-31",
      "status": "Active",
      "tenants": [
        {
          "id": 789,
          "firstName": "John",
          "lastName": "Doe"
        }
      ]
    }
  ],
  "count": 1
}

Example: Get Lease

Retrieve details of a specific lease by ID.

Parameters:

• lease_id (int, required): The lease ID

Example Request:

{
  "name": "get_lease",
  "arguments": {
    "lease_id": 12345
  }
}

Example Response:

{
  "id": 12345,
  "propertyId": 123,
  "unitId": 456,
  "leaseType": "Fixed",
  "leaseFromDate": "2024-01-01",
  "leaseToDate": "2024-12-31",
  "status": "Active",
  "rentCycle": "Monthly",
  "rentAmount": 2000.00,
  "securityDepositAmount": 2000.00,
  "tenants": [
    {
      "id": 789,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phoneNumbers": {
        "home": "555-0100"
      }
    }
  ],
  "createdDateTime": "2024-01-01T10:00:00Z",
  "lastModifiedDateTime": "2024-01-01T10:00:00Z"
}

Example: Create Lease

Create a new lease agreement.

Required Parameters:

• lease_type (str): Lease type - "AtWill" (month-to-month), "Fixed" (specific dates), or "FixedWithRollover"
• unit_id (int): Unit ID for the lease
• lease_from_date (str): Start date (format: YYYY-MM-DD)
• send_welcome_email (bool): Whether to send welcome email to tenants

Optional Parameters:

• lease_to_date (str): End date (required for Fixed/FixedWithRollover leases)
• tenant_ids (list[int]): Existing tenant IDs to add (max 5)
• tenants (list[object]): New tenants to create (max 5)
• applicant_ids (list[int]): Approved applicant IDs to convert to tenants (max 5)
• rent (object): Rent configuration with cycle and charges
• security_deposit (object): Security deposit details
• prorated_first_month_rent (float): Prorated first month rent
• prorated_last_month_rent (float): Prorated last month rent
• cosigners (list[object]): Cosigner details

Example Request (Minimal - Using Existing Tenant):

{
  "name": "create_lease",
  "arguments": {
    "lease_data": {
      "lease_type": "Fixed",
      "unit_id": 456,
      "lease_from_date": "2025-01-01",
      "lease_to_date": "2025-12-31",
      "send_welcome_email": true,
      "tenant_ids": [789]
    }
  }
}

Example Request (Complete with New Tenant and Rent):

{
  "name": "create_lease",
  "arguments": {
    "lease_data": {
      "lease_type": "Fixed",
      "unit_id": 456,
      "lease_from_date": "2025-01-01",
      "lease_to_date": "2025-12-31",
      "send_welcome_email": true,
      "tenants": [
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane.smith@example.com",
          "phone_numbers": {
            "home": "555-0200"
          },
          "address": {
            "address_line1": "123 Main St",
            "city": "Springfield",
            "state": "IL",
            "postal_code": "62701",
            "country": "US"
          }
        }
      ],
      "rent": {
        "cycle": "Monthly",
        "charges": [
          {
            "gl_account_id": 1001,
            "amount": 2000.00
          }
        ]
      },
      "security_deposit": {
        "due_date": "2025-01-01",
        "amount": 2000.00
      }
    }
  }
}

Example Response:

{
  "id": 12346,
  "propertyId": 123,
  "unitId": 456,
  "leaseType": "Fixed",
  "leaseFromDate": "2025-01-01",
  "leaseToDate": "2025-12-31",
  "status": "Active",
  "rentCycle": "Monthly",
  "rentAmount": 2000.00,
  "securityDepositAmount": 2000.00,
  "tenants": [
    {
      "id": 790,
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com"
    }
  ],
  "createdDateTime": "2024-11-07T00:00:00Z"
}

Field Descriptions:

Lease Types:

• AtWill: Month-to-month lease with no end date. Automatic transactions continue until manually ended.
• Fixed: Lease with specific start/end dates. Moves to expired on end date, stops automatic transactions.
• FixedWithRollover: Lease that converts to AtWill status at end date, continuing automatic transactions.

Rent Configuration:

• cycle: Rent frequency - "Monthly", "Weekly", "Every2Weeks", "Quarterly", "Yearly", "Every2Months", "Daily", "Every6Months", "OneTime"
• charges: Array of rent charges with GL account ID and amount

Tenant Creation:

• Can provide up to 5 tenants via tenant_ids (existing), tenants (new), or applicant_ids (approved applicants)
• Required tenant fields: first_name, last_name, address
• Optional: email, phone_numbers, date_of_birth, emergency_contact, etc.

Example Usage

Example Prompts

"List all rental properties in Buildium"

"Show me lease #12345"

"Create a new lease for property 100, unit 205"

"List all associations"

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/luthersystems/mcp-server-buildium.git
cd mcp-server-buildium

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -e ".[dev]"

Running Tests

# Run unit tests (no credentials needed)
uv run pytest tests/ --ignore=tests/test_integration.py

# Run with coverage
uv run pytest --cov=mcp_server_buildium --cov-report=html

# Run linter
uv run ruff check .

# Format code
uv run ruff format .

Integration Tests (Optional)

Integration tests validate real Buildium API authentication. They are skipped by default and only run when you provide real credentials.

To enable integration tests:

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Fill in your Buildium credentials in .env:

   BUILDIUM_BASE_URL=https://apisandbox.buildium.com/
   BUILDIUM_CLIENT_ID=your-client-id
   BUILDIUM_CLIENT_SECRET=your-client-secret
   

3. Run integration tests:

   uv run pytest tests/test_integration.py -v
   

Test Credentials (Sandbox):

• Client ID: 54f6ac5b-5629-4934-a930-d2c8174fcf4a
• Client Secret: tHXJx7mFoCEXtqCvBL3oV1Fv6hHb5WVokKHIvT1cUIA=
• Base URL: https://apisandbox.buildium.com/

CI/CD Setup (GitHub Actions)

To run integration tests in GitHub Actions:

1. Add GitHub repository secrets:

   • Go to your repo → Settings → Secrets and variables → Actions
   • Add the following secrets:
     • BUILDIUM_BASE_URL: https://apisandbox.buildium.com/
     • BUILDIUM_CLIENT_ID: Your client ID
     • BUILDIUM_CLIENT_SECRET: Your client secret

2. The CI workflow will automatically run integration tests when these secrets are present

Note: The integration tests will be skipped in PRs from forks (for security), but will run on pushes to main/develop branches.

What the integration tests verify:

• ✅ OAuth authentication works with your credentials
• ✅ Access token can be obtained successfully
• ✅ API calls work (tests list_associations, list_rentals, list_leases)
• ✅ Token refresh mechanism works

Note: Integration tests require a Buildium developer account (sandbox environment recommended).

Generating SDK from OpenAPI Spec

If you want to generate a Python SDK from the Buildium OpenAPI spec:

# Generate SDK (requires Java for OpenAPI Generator)
make generate-sdk

# The generated SDK will be in buildium_sdk/ directory

See Makefile for more details.

Project Structure

mcp-server-buildium/
├── src/mcp_server_buildium/
│   ├── __init__.py
│   ├── server.py           # Main FastMCP server
│   ├── config.py           # Configuration management
│   ├── buildium_client.py  # OAuth auth & API client
│   └── tools/
│       ├── associations.py # Association tools
│       ├── leases.py       # Lease tools
│       └── rentals.py      # Rental tools
├── tests/
│   ├── test_buildium_client.py
│   └── test_integration.py
├── pyproject.toml
└── README.md

Troubleshooting

"Failed to obtain access token"

• Verify client ID and secret are correct
• Check base URL is correct (sandbox vs production)
• Ensure token URL is accessible
• Verify scopes are correct

"401 Unauthorized"

• Check credentials are valid
• Verify API endpoint URLs
• Ensure OAuth scopes include required permissions

"Connection timeout"

• Check internet connectivity
• Verify firewall settings
• Try sandbox environment first

API Endpoints

• Production: https://api.buildium.com/
• Sandbox: https://apisandbox.buildium.com/

Security Best Practices

1. Never commit credentials - Use .gitignore and environment variables
2. Use secrets management - Store credentials in secure vaults (AWS Secrets Manager, etc.)
3. Rotate credentials regularly - Generate new client secrets periodically
4. Limit token lifetime - Use shorter expiration for sensitive operations
5. Monitor API usage - Check Buildium dashboard for unusual activity
6. Use sandbox environment - Test with sandbox accounts before production

Architecture

• Language: Python 3.11+
• Framework: FastMCP
• Auth: OAuth 2.0 client credentials flow
• Transport: stdio (MCP protocol)
• HTTP Client: httpx
• Testing: pytest with mocks

References

• Buildium Developer Documentation
• Model Context Protocol
• FastMCP Framework
• OAuth 2.0 Client Credentials Flow

License

MIT

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Support

This is an experimental community project. For Buildium API issues, consult the Buildium Developer Center.