ledger_balance
Display account balances with filtering by date, depth, or account pattern. Group results by day, week, month, or year for customized financial reporting and analysis.
Instructions
Show account balances
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Implementation Reference
- main.py:132-157 (handler)The main handler function for the 'ledger_balance' tool, decorated with @mcp.tool for automatic registration. It constructs the 'ledger balance' CLI command based on the input parameters and executes it using the run_ledger helper.
@mcp.tool(description="Show account balances") def ledger_balance(params: LedgerBalance) -> str: cmd = ["balance"] if params.query: cmd.append(params.query) if params.begin_date: cmd.extend(["-b", params.begin_date]) if params.end_date: cmd.extend(["-e", params.end_date]) if params.depth is not None: cmd.extend(["--depth", str(params.depth)]) if params.monthly: cmd.append("--monthly") if params.weekly: cmd.append("--weekly") if params.daily: cmd.append("--daily") if params.yearly: cmd.append("--yearly") if params.flat: cmd.append("--flat") if params.no_total: cmd.append("--no-total") return run_ledger(cmd) - main.py:18-33 (schema)Pydantic model defining the input schema for the ledger_balance tool, specifying optional parameters for filtering, date ranges, depth, and various display options.
class LedgerBalance(BaseModel): query: Optional[str] = Field(None, description="Filter accounts by regex pattern") begin_date: Optional[str] = Field( None, description="Start date for transactions (YYYY/MM/DD)" ) end_date: Optional[str] = Field( None, description="End date (exclusive) for transactions (YYYY/MM/DD)" ) depth: Optional[int] = Field(None, description="Limit account depth displayed") monthly: bool = Field(False, description="Group by month") weekly: bool = Field(False, description="Group by week") daily: bool = Field(False, description="Group by day") yearly: bool = Field(False, description="Group by year") flat: bool = Field(False, description="Show full account names without indentation") no_total: bool = Field(False, description="Don't show the final total") - main.py:107-129 (helper)Supporting helper function that runs ledger CLI commands securely via subprocess.run, handles the LEDGER_FILE path, validates arguments against injection, and manages errors.
def run_ledger(args: List[str]) -> str: try: if not LEDGER_FILE: return "Ledger file path not set. Please provide it via --ledger-file argument or LEDGER_FILE environment variable." # Validate inputs to prevent command injection for arg in args: if ";" in arg or "&" in arg or "|" in arg: return "Error: Invalid characters in command arguments." result = subprocess.run( ["ledger", "-f", LEDGER_FILE] + args, check=True, text=True, capture_output=True, ) return result.stdout except subprocess.CalledProcessError as e: error_message = f"Ledger command failed: {e.stderr}" if "couldn't find file" in e.stderr: error_message = f"Ledger file not found at {LEDGER_FILE}. Please provide a valid path via --ledger-file argument or LEDGER_FILE environment variable." return error_message