Belong MCP Server

An MCP (Model Context Protocol) server that exposes the Belong Resident Application APIs as tools. This lets AI assistants like Claude interact with your Belong society account -- manage visitors, vehicles, maintenance issues, amenity bookings, finances, and more.

Prerequisites

• Node.js v18 or later
• An active Belong resident account

Setup

1. Clone the repo

   git clone https://github.com/arjunbhasin/belong-mcp.git
   cd belong-mcp
   

2. Install dependencies

   npm install
   

3. Create a .env file (optional -- you can authenticate via OTP through the MCP tools instead)

   cp .env.example .env
   

   If you already have tokens, populate them:

   ACCESS_TOKEN=your_access_token
   REFRESH_TOKEN=your_refresh_token
   MOBILE_NUMBER=your_mobile_number
   

Running the Server

The server communicates over stdio, which is how MCP clients (like Claude Code or Claude Desktop) connect to it.

node index.js

Or using the npm script:

npm start

Connecting to Claude Code

Add to your Claude Code MCP config (~/.claude/claude_code_config.json or project-level .mcp.json):

{
  "mcpServers": {
    "belong-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/belong-mcp/index.js"]
    }
  }
}

Connecting to Claude Desktop

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

{
  "mcpServers": {
    "belong-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/belong-mcp/index.js"]
    }
  }
}

Authentication

There are two ways to authenticate:

Option 1: OTP via MCP tools (recommended)

Once the server is connected, use the built-in authentication tools:

1. Call request_otp with your mobile number
2. Call verify_otp with the OTP you received
3. Tokens are saved to .env automatically

Option 2: Manual .env file

If you have tokens from another session, add them to the .env file directly (see Setup step 3).

The server automatically refreshes expired access tokens using the refresh token.

Available Tools

Authentication

Tool	Description
request_otp	Send OTP to mobile number
verify_otp	Verify OTP to complete login
check_auth_status	Check current auth state

Profile & Flats

Tool	Description
get_resident_profile	Get your profile (name, mobile, email)
get_flat_access	Get flat feature flags and access details
get_occupancy_detail	Get tower/wing/floor info for a flat
list_flats	List all your associated flats
list_flats_by_occupancy	Filter flats by occupancy ID
get_flats_by_resident_ids	Look up flats for specific residents

Visitors & Gate

Tool	Description
get_visitor_approvals	List gate entries for a date
get_approvals_count	Monthly visitor approval count
get_exit_passes	Material movement exit passes
get_entry_stats	Visitor entry statistics
list_visitor_companies	Delivery companies by category

Staff & Services

Tool	Description
list_service_staffs	Registered staff (maid, cook, etc.)
list_service_staff_bookings	Staff booking schedules
list_service_types	Available service types

Vehicles

Tool	Description
list_resident_vehicles	Vehicles registered to a flat
search_vehicles	Search by registration number
list_vehicle_brands	Available vehicle brands

Maintenance Issues

Tool	Description
list_maintenance_issues	Your complaints and issues
list_issue_categories	Available issue categories
get_issue_stats	Issue statistics

Amenities

Tool	Description
list_booked_slots	Amenity bookings (gym, pool, etc.)
get_booking_stats	Booking statistics

Community

Tool	Description
get_announcements	Community announcements
list_community_feeds	Community feed posts
get_banners	Promotional banners
list_campaigns	Active campaigns
list_rwa_members	RWA committee members

Buggy Service

Tool	Description
list_buggy_stops	Golf cart pickup/drop stops
get_buggy_activity	Buggy ride history

Chat

Tool	Description
list_chat_enabled_residents	Residents available for chat
list_chat_wings	Wings available for chat
list_chat_flat_residents	Residents on a floor

Infrastructure

Tool	Description
get_towers	Buildings in a project
get_module_access	Enabled modules/features
list_external_services	Integrated services (laundry, food)
list_languages	Available languages

Finance & Billing

Tool	Description
get_financial_ledger	Transaction history for a date range
get_invoice_stats	Unpaid amounts, interest, balance
list_demandnote_requests	Payment demands from management
get_payment_config	Payment method configuration

Notifications & Delivery

Tool	Description
get_notifications_count	Unread notification count
get_delivery_preferences	Auto-approve delivery settings

License

ISC