Aptly Property Management MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Aptly Property Management platform for comprehensive property workflow management.

Features

🏠 Property Management Integration - Complete integration with Aptly's property management platform
📋 Work Order Management - Create, update, search, and manage work orders (cards)
💬 Comments & Communication - Add comments and notes to work orders
📎 File Attachments - Upload and manage files attached to work orders
🔄 System Integrations - Sync with property management systems like Propertyware, Yardi, RealPage
📊 Analytics & Reporting - Generate comprehensive property management reports
🛡️ Enterprise Security - Secure API authentication and data validation

Installation

npm install @rashidazarang/aptly-property-management-mcp

Quick Start

Environment Setup

Set your Aptly API token:

export APTLY_API_TOKEN="your-aptly-api-token"
export APTLY_BASE_URL="https://api.getaptly.com"  # Optional

Using with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "aptly-property-management": {
      "command": "npx",
      "args": ["@rashidazarang/aptly-property-management-mcp"],
      "env": {
        "APTLY_API_TOKEN": "your-aptly-api-token"
      }
    }
  }
}

Using with MCP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@rashidazarang/aptly-property-management-mcp'],
  env: {
    APTLY_API_TOKEN: 'your-aptly-api-token'
  }
});

const client = new Client(
  {
    name: 'aptly-client',
    version: '1.0.0',
  },
  {
    capabilities: {},
  }
);

await client.connect(transport);

Available Tools

Connection & Setup

• aptly_test_connection - Test API connection
• aptly_get_boards - Get all accessible boards

Work Order Management

• aptly_get_cards - Get cards from a board with filters
• aptly_create_card - Create new work order
• aptly_update_card - Update existing work order
• aptly_delete_card - Delete work order
• aptly_search_cards - Search across all work orders

Communication

• aptly_get_comments - Get comments for a work order
• aptly_add_comment - Add comment to work order

File Management

• aptly_get_files - Get file attachments
• aptly_upload_file - Upload file to work order

System Integration

• aptly_get_integrations - List available integrations
• aptly_sync_integration - Trigger sync with PM systems

Analytics

• aptly_generate_report - Generate property management reports

Available Resources

Boards

• aptly://boards - List all boards
• aptly://board/{id} - Specific board details
• aptly://board/{id}/cards - Cards in a board

Cards (Work Orders)

• aptly://card/{id} - Specific card details
• aptly://card/{id}/comments - Card comments
• aptly://card/{id}/files - Card file attachments

System Resources

• aptly://integrations - Available integrations
• aptly://reports - Analytics reports

Usage Examples

Creating Work Orders

# Using Claude Desktop with MCP
"Create a work order for broken faucet at 123 Main St, Unit 4B"
"New urgent work order: HVAC not working in Building A"
"Create maintenance request for tenant John Doe - leaky pipe in bathroom"

Managing Work Orders

"Update work order WO-123 status to completed"
"Assign work order WO-456 to Mike Rodriguez" 
"Set work order WO-789 priority to urgent"
"Add comment to WO-123: Parts ordered, will repair tomorrow"

Searching and Reporting

"Show me all high priority work orders"
"Find work orders for Oak Street Apartments"
"Generate monthly work order summary report"
"List all open plumbing work orders"

Integration Management

"Sync data from Propertyware"
"Show available property management integrations"
"Get status of last sync operation"

Tool Schemas

Create Work Order

{
  "name": "aptly_create_card",
  "arguments": {
    "boardId": "board-123",
    "title": "HVAC Repair - Unit 5B", 
    "description": "Air conditioning not cooling properly",
    "status": "new",
    "priority": "high",
    "location": {
      "street_1": "123 Main Street",
      "city": "Springfield", 
      "state": "IL",
      "zip_code": "62701",
      "unit_number": "5B"
    },
    "tenant_info": {
      "name": "Jennifer Adams",
      "phone": "555-0123",
      "email": "[email protected]"
    },
    "custom_fields": {
      "work_order_type": "hvac",
      "estimated_hours": 2
    }
  }
}

Search Work Orders

{
  "name": "aptly_search_cards",
  "arguments": {
    "query": "broken faucet",
    "status": "open",
    "priority": "high",
    "date_from": "2024-01-01",
    "limit": 20
  }
}

Generate Report

{
  "name": "aptly_generate_report", 
  "arguments": {
    "report_type": "work_orders",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
    "filters": {
      "status": ["completed", "in_progress"]
    }
  }
}

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | APTLY_API_TOKEN | Your Aptly API token | Required | | APTLY_BASE_URL | Aptly API base URL | https://api.getaptly.com | | APTLY_TIMEOUT | Request timeout (ms) | 30000 |

Getting Your API Token

1. Log into your Aptly Property Management account
2. Navigate to Settings → API Settings
3. Generate a new API token
4. Copy the token and set it as APTLY_API_TOKEN

Development

Setup

# Clone the repository
git clone https://github.com/rashidazarang/aptly-property-management-mcp.git
cd aptly-property-management-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Build the project
npm run build

# Run tests
APTLY_API_TOKEN=your-token npm test

# Start the MCP server
npm start

Testing

# Run connection test
APTLY_API_TOKEN=your-token npm test

# Run with test card creation
APTLY_API_TOKEN=your-token npm test -- --create-test-card

# Run type checking
npm run type-check

# Run linting
npm run lint

Error Handling

The MCP server provides comprehensive error handling:

• Authentication Errors - Invalid or expired API tokens
• Rate Limiting - Automatic rate limit handling with retries
• Validation Errors - Input validation with helpful error messages
• Network Errors - Connection and timeout handling
• API Errors - Aptly API error responses with context

Security

• All API communication uses HTTPS
• API tokens are securely managed through environment variables
• Input validation prevents injection attacks
• Rate limiting prevents API abuse
• No sensitive data is logged

Property Management Integrations

Supported property management systems:

• Propertyware - Full bi-directional sync
• Yardi - Work order and tenant sync
• RealPage - Maintenance workflow integration
• AppFolio - Basic work order sync
• Rent Manager - Tenant and property sync

Troubleshooting

Common Issues

1. Authentication Failed

   Error: Authentication failed - invalid API token

   • Verify your API token is correct
   • Check token hasn't expired
   • Ensure token has required permissions

2. Rate Limit Exceeded

   Error: Rate limit exceeded

   • The server automatically handles rate limits
   • Reduce request frequency if needed

3. Board Not Found

   Error: Board not found

   • Verify board ID is correct
   • Check you have access to the board
   • Use aptly_get_boards to list available boards

Debug Mode

Set LOG_LEVEL=DEBUG for detailed logging:

LOG_LEVEL=DEBUG APTLY_API_TOKEN=your-token npm start

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Complete Aptly API integration
• Full MCP compliance
• Work order management tools
• Comment and file attachment support
• Property management system integrations
• Analytics and reporting tools
• Comprehensive error handling
• Rate limiting and security features

Made with ❤️ for property management teams using AI assistants.