Society Maintenance Tracker — MCP Server

An MCP (Model Context Protocol) server that exposes society maintenance and expense data as tools, so any MCP-compatible AI agent (Claude Desktop, Cursor, watsonx, etc.) can query it using natural language.

---

What it does

The server reads two Excel files (Maintenance.xlsx and Expenses.xlsx) and registers 8 tools that an AI agent can call:

Tool	What it answers
tool_get_all_months	Which months have data?
tool_get_pending_maintenance	Which flats haven't paid? (by month or year)
tool_get_collected_maintenance	Which flats have paid? (by month or year)
tool_get_balance_sheet	Income vs expenses — surplus or deficit?
tool_get_expense_summary	Expenses broken down by category
tool_get_flat_history	Full payment history for a specific flat
tool_download_pending_report	Generate & save pending maintenance Excel report
tool_download_balance_report	Generate & save balance sheet Excel report

---

Project structure

Society Maintenance Tracker/
├── server.py               # MCP server entry point (8 tools registered)
├── server/
│   ├── __init__.py
│   └── data_loader.py      # Loads & queries Maintenance.xlsx + Expenses.xlsx
├── reports/
│   ├── __init__.py
│   └── generator.py        # Generates styled Excel reports
├── data/                   # ← YOU must supply these (not included in repo)
│   ├── Maintenance.xlsx
│   └── Expenses.xlsx
├── downloads/              # Auto-created — generated reports saved here
├── requirements.txt
├── Dockerfile
└── README.md

---

Prerequisites

• Python 3.11 or 3.12
• The two Excel data files (see Data files below)

---

Installation

1. Clone the repo

git clone https://github.com/YOUR_USERNAME/society-maintenance-tracker.git
cd society-maintenance-tracker

2. Create a virtual environment (recommended)

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Add your data files

Create a data/ folder and place your Excel files inside:

data/
├── Maintenance.xlsx    ← sheet name must be "Maintenance"
└── Expenses.xlsx       ← sheet name must be "Expenses"

Expected columns:

Maintenance.xlsx — Month | Date | Flat No | Name | Amount | Late Charges

Expenses.xlsx — Month | Date | Expence Type | Details | Amount | Spend By

---

Running the server

stdio mode — for AI agents that spawn it as a subprocess (Claude Desktop, Cursor, etc.)

python server.py

⚠️ Do not type into the terminal in this mode — the server speaks JSON-RPC over stdin/stdout. It will look frozen; that is normal.

SSE mode — for persistent servers / external clients

python server.py --sse

Server listens at http://localhost:8100/sse.

---

Connecting to AI clients

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "society-maintenance": {
      "command": "python",
      "args": ["C:/full/path/to/society-maintenance-tracker/server.py"]
    }
  }
}

Restart Claude Desktop. You can now ask questions like:

• "Which flats haven't paid maintenance for January 2024?"
• "What is the balance sheet for 2024?"
• "Give me the payment history for flat 601."

Cursor / VS Code (MCP extension)

Add to your MCP settings:

{
  "society-maintenance": {
    "command": "python",
    "args": ["/full/path/to/server.py"]
  }
}

MCP Inspector (browser UI — best for testing)

npx @modelcontextprotocol/inspector python server.py

Opens at http://localhost:5173 — browse and call all tools interactively.

---

Running with Docker

# Build
docker build -t society-mcp .

# Run (mount your local data/ folder into the container)
docker run -v $(pwd)/data:/app/data society-mcp

---

Testing

Quick data sanity check

python -c "
import sys; sys.path.insert(0, '.')
from server.data_loader import get_all_months, get_balance_sheet
print(get_all_months())
print(get_balance_sheet(year=2024))
"

Full MCP protocol test (stdio)

python _test_server.py

This sends a proper JSON-RPC handshake and lists all registered tools.

---

Data files

The data/ folder is excluded from this repository (see .gitignore) because the Excel files contain private resident information.

To use this server:

1. Create your own Maintenance.xlsx and Expenses.xlsx following the column format above.
2. Place them in the data/ folder.
3. The server will load them automatically on first tool call.

---

Month format

Months in the Excel file must follow the pattern MonthName_YYYY, e.g.:

Jan_2024   Feb_2024   March_2024   April_2024
May_2024   June_2024  July_2024    Aug_2024
Sep_2024   Oct_2024   Nov_2024     Dec_2024

The server normalises common variants automatically (january_2024, MARCH_2025, jun_2024, etc.).

---

License

MIT