Buildium MCP服务器

实验性 用于Buildium Property Management API的模型上下文协议（MCP）服务器，使用Python+FastMCP构建。使用API密钥身份验证进行服务器到服务器的通信。

⚠️ 状态和免责声明

实验性：未准备好生产；无SLA；API和行为可能会改变。
与Buildium没有关联：这是一种社区融合。Buildium是Buildium，LLC的商标。
安全：做不泄露秘密。将客户ID和机密视为敏感信息；使用秘密管理器。 使用风险自负。

特性

🔐 API密钥验证 -通过标头进行安全的服务器到服务器身份验证
🏘️ 12个类别中的81个工具 -全面的物业管理覆盖
📋 选择性工具加载 -仅启用所需的类别
🏢 多属性类型 -租金、协会和单位
🔌 MCP协议 -与Claude Desktop、Cursor和其他MCP客户端兼容

需求

Python 3.11+
uv 包管理器（或 pip)
Buildium API凭据（客户端ID和客户端机密）

安装

使用 `uv` （推荐）

# 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"

使用 `pip`

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

配置

使用环境变量配置服务器：

# 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

工具类别

使用控制启用哪些工具类别 BUILDIUM_CATEGORIES 环境变量：

类别	工具	描述
`associations`	6	业主协会管理
`leases`	5	租赁协议和交易
`rentals`	5	租赁物业和房源
`applicants`	10	租赁申请人和申请
`tenants`	7	租户管理（租金和协会）
`owners`	8	业主管理
`units`	7	个人单位管理
`vendors`	7	供应商和服务提供商管理
`tasks`	5	任务和待办事项管理
`bills`	7	账单和付款管理
`files`	8	文件和档案管理
`bank_accounts`	6	银行账户和交易管理

总计：81个工具

如果 BUILDIUM_CATEGORIES 如果未设置，则启用了所有12个类别中的所有81个工具。

环境文件

创建一个 .env 文件（复制自 .env.example):

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

用法

运行服务器

# With uv
uv run mcp-server-buildium

# Or with Python
python -m mcp_server_buildium.server

与Claude Desktop一起使用

添加到您的Claude桌面配置(~/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"
      }
    }
  }
}

可用工具（共81个）

协会（6个工具）

list_associations -列出所有关联
get_association -按ID获取关联详细信息
create_association -创建新关联
update_association -更新现有关联
list_association_board_members -列出协会的董事会成员
list_association_ownership_accounts -列出关联的所有权帐户

租赁（5件工具）

list_leases -列出带有可选筛选器的租约
get_lease -按ID获取租赁详细信息
create_lease -创建新租约
update_lease -更新现有租约
list_lease_transactions -列出租赁交易记录

租赁（5工具）

list_rentals -列出租赁物业
get_rental -按ID获取租赁物业详细信息
create_rental -创建新的租赁物业
update_rental -更新现有的租赁物业
list_unit_listings -列出出租单位列表

申请人（10个工具）

list_applicants -列出租房申请人
get_applicant -按ID获取申请人详细信息
create_applicant -创建新申请人
update_applicant -更新现有申请人
list_applicant_applications -列出申请人的申请
get_application -按ID获取应用程序详细信息
update_application -更新应用程序
list_applicant_groups -列出申请人群体
create_applicant_group -创建新的申请人组
update_applicant_group -更新申请人组

租户（7工具）

list_rental_tenants -列出租赁租户
get_rental_tenant -按ID获取租赁租户详细信息
create_rental_tenant -创建新的租赁租户
update_rental_tenant -更新租赁租户
list_association_tenants -列出协会租户
create_association_tenant -创建新的关联租户
update_association_tenant -更新关联租户

所有者（8工具）

list_rental_owners -列出租赁物业所有者
get_rental_owner -通过ID获取租赁所有者详细信息
create_rental_owner -创建新的租赁所有者
update_rental_owner -更新租赁所有者
list_association_owners -列出协会所有者
get_association_owner -按ID获取关联所有者详细信息
create_association_owner -创建新的关联所有者
update_association_owner -更新关联所有者

单元（7个工具）

list_rental_units -列出租赁单位
get_rental_unit -通过ID获取租赁单元详细信息
create_rental_unit -创建新的租赁单元
update_rental_unit -更新租赁单元
list_association_units -列出关联单位
create_association_unit -创建新的关联单元
update_association_unit -更新关联单位

供应商（7种工具）

list_vendors -列出供应商
get_vendor -按ID获取供应商详细信息
create_vendor -创建新供应商
update_vendor -更新现有供应商
list_vendor_categories -列出供应商类别
create_vendor_category -创建新的供应商类别
update_vendor_category -更新供应商类别

任务（5个工具）

list_tasks -列出任务
get_task -按ID获取任务详细信息
list_task_categories -列出任务类别
create_task_category -创建新的任务类别
update_task_category -更新任务类别

账单（7个工具）

list_bills -列出账单
get_bill -按ID获取账单详细信息
create_bill -创建新账单
update_bill -更新现有账单
list_bill_payments -列出账单付款
get_bill_payment -按ID获取账单付款详细信息
create_bill_payment -创建新的账单付款

文件（8个工具）

list_files -列出文件
get_file -按ID获取文件详细信息
update_file -更新文件元数据
create_file_upload_request -创建文件上传请求
create_file_download_request -创建文件下载请求
list_file_categories -列出文件类别
create_file_category -创建新的文件类别
update_file_category -更新文件类别

银行账户（6个工具）

list_bank_accounts -列出银行账户
get_bank_account -按ID获取银行账户详细信息
create_bank_account -创建新的银行账户
update_bank_account -更新银行账户
list_bank_account_transactions -列出银行账户的交易记录
get_bank_account_transaction -按ID获取银行账户交易详细信息

工具请求/响应示例

本节提供了关键MCP工具的详细模式和示例。

示例：列出租约

使用可选筛选器（属性、单位、状态）查询租赁。

参数：

property_id （int，可选）：按属性ID筛选
unit_id （int，可选）：按单位ID过滤
lease_status （str，可选）：按状态筛选（例如，“活动”、“未来”、“过去”、“已过期”）
limit （int，可选）：最大结果（默认值：100）
offset （int，可选）：分页偏移量（默认值：0）

示例请求（无筛选器）：

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

示例请求（带过滤器）：

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

示例响应：

{
  "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
}

示例：获取租赁

按ID检索特定租约的详细信息。

参数：

lease_id （int，必填）：租约ID

请求示例：

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

示例响应：

{
  "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"
}

示例：创建租约

创建新的租赁协议。

所需参数：

lease_type （str）：租赁类型- "AtWill" （逐月）， "Fixed" （具体日期），或 "FixedWithRollover"
unit_id （int）：租赁的单元ID
lease_from_date （str）：开始日期（格式： YYYY-MM-DD)
send_welcome_email （bool）：是否向租户发送欢迎电子邮件

可选参数：

lease_to_date （str）：结束日期（固定/固定展期租约需要）
tenant_ids （list\[int\]）：要添加的现有租户ID（最多5个）
tenants （list\[object\]）：要创建的新租户（最多5个）
applicant_ids （list\[int\]）：批准的申请人ID转换为租户（最多5个）
rent （对象）：带周期和费用的租金配置
security_deposit （对象）：保证金明细
prorated_first_month_rent （浮动）：按比例计算的首月租金
prorated_last_month_rent （浮动）：按比例计算的上月租金
cosigners （列表\[对象\]）：Cosigner详细信息

示例请求（最小化-使用现有租户）：

{
  "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]
    }
  }
}

示例请求（填写新租户和租金）：

{
  "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
      }
    }
  }
}

示例响应：

{
  "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"
}

字段描述：

租赁类型：

AtWill：按月租赁，无终止日期。自动事务将继续，直到手动结束。
Fixed：具有特定开始/结束日期的租约。移动到结束日期到期，停止自动交易。
FixedWithRollover：在结束日期转换为AtWill状态的租约，继续自动交易。

租金配置：

cycle：租金频率- "Monthly", "Weekly", "Every2Weeks", "Quarterly", "Yearly", "Every2Months", "Daily", "Every6Months", "OneTime"
charges：带有总账账户ID和金额的租金数组

租户创建：

最多可通过以下方式提供5名租户 tenant_ids （现有）， tenants （新），或 applicant_ids （已批准的申请人）
必填租户字段： first_name, last_name, address
可选： email, phone_numbers, date_of_birth, emergency_contact等等。

示例用法

示例提示

“列出Buildium中的所有租赁物业”

“显示租约#12345”

为物业100，单元205创建新租约

“列出所有关联”

发展

设置开发环境

# 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]"

运行测试

# 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 .

集成测试（可选）

集成测试验证真实的Buildium API身份验证。他们是 默认情况下跳过 并且仅在您提供真实凭据时运行。

要启用集成测试，请执行以下操作：

复制 .env.example 到 .env:

   cp .env.example .env

在中填写您的Buildium凭据 .env:

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

运行集成测试：

   uv run pytest tests/test_integration.py -v

测试证书（沙盒）：

客户端ID: 54f6ac5b-5629-4934-a930-d2c8174fcf4a
客户端密码： tHXJx7mFoCEXtqCvBL3oV1Fv6hHb5WVokKHIvT1cUIA=
基本URL: https://apisandbox.buildium.com/

CI/CD设置（GitHub操作）

要在GitHub Actions中运行集成测试，请执行以下操作：

添加GitHub存储库机密：

- 转到您的仓库→ 设置 → 秘密和变量 → 行动 - 添加以下机密： - BUILDIUM_BASE_URL: https://apisandbox.buildium.com/ - BUILDIUM_CLIENT_ID：您的客户ID - BUILDIUM_CLIENT_SECRET：您的客户机密

CI工作流将自动运行集成测试 当这些秘密出现时

备注：在fork的PR中，集成测试将被跳过（出于安全考虑），但将在主/开发分支的推送上运行。

集成测试验证了什么：

✅ OAuth身份验证使用您的凭据
✅ 可以成功获取访问令牌
✅ API调用工作（测试 list_associations, list_rentals, list_leases)
✅ 令牌刷新机制工作

备注：集成测试需要Buildium开发人员帐户（建议使用沙盒环境）。

从OpenAPI规范生成SDK

如果你想从Buildium OpenAPI规范生成Python SDK：

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

# The generated SDK will be in buildium_sdk/ directory

看 Makefile 了解更多详情。

项目结构

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

故障排除

“获取访问令牌失败”

验证客户端ID和密码是否正确
检查基本URL是否正确（沙盒与生产）
确保令牌URL可访问
验证范围是否正确

“401未经授权”

检查凭据是否有效
验证API端点URL
确保OAuth范围包括所需的权限

“连接超时”

检查互联网连接
验证防火墙设置
先尝试沙盒环境

API终点

生产: https://api.buildium.com/
沙盒: https://apisandbox.buildium.com/

安全最佳实践

从不提交凭据 -使用 .gitignore 和环境变量
使用机密管理 -将凭据存储在安全保管库中（AWS Secrets Manager等）
定期轮换凭据 -定期生成新的客户端机密
限制令牌寿命 -对敏感操作使用较短的过期时间
监控API使用情况 -检查Buildium仪表板是否有异常活动
使用沙盒环境 -生产前使用沙盒帐户进行测试

建筑

语言：Python 3.11+
框架：FastMCP
认证：OAuth 2.0客户端凭据流
运输：stdio（MCP协议）
HTTP客户端：httpx
测试：带模拟的pytest

参考文献

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

支持

这是一个实验性的社区项目。有关Buildium API的问题，请参阅 Buildium开发者中心.

MCP Server Buildium

快速接入

详细介绍

Buildium MCP服务器

⚠️ 状态和免责声明

特性

需求

安装

使用 uv （推荐）

使用 pip

配置

工具类别

环境文件

用法

运行服务器

与Claude Desktop一起使用

可用工具（共81个）

协会（6个工具）

租赁（5件工具）

租赁（5工具）

申请人（10个工具）

租户（7工具）

所有者（8工具）

单元（7个工具）

供应商（7种工具）

任务（5个工具）

账单（7个工具）

文件（8个工具）

银行账户（6个工具）

工具请求/响应示例

示例：列出租约

示例：获取租赁

示例：创建租约

示例用法

示例提示

发展

设置开发环境

运行测试

集成测试（可选）

CI/CD设置（GitHub操作）

从OpenAPI规范生成SDK

项目结构

故障排除

“获取访问令牌失败”

“401未经授权”

“连接超时”

API终点

安全最佳实践

建筑

参考文献

许可证

贡献

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

使用 `uv` （推荐）

使用 `pip`