TreasuryOS

TreasuryOS is an MCP server that enables Claude to act as a treasury analyst by connecting bank accounts, transactions, vendor payables, and debt covenants to deliver actionable treasury insights. It is designed to turn complex data into practical, money-saving recommendations that you can discuss with clients or stakeholders in real time.

How to use

To use TreasuryOS, connect your MCP client to the TreasuryOS MCP server and start chaining tools in natural language conversations. You can begin by asking Claude to pull a current cash position, identify idle cash, forecast cash flow, evaluate working capital health, optimize payment timing, scanning FX exposure, and monitor debt covenants. The system is designed to surface insights a great relationship manager would share with a client in a real meeting.

How to install

Prerequisites you need on your machine are Python 3.11 or newer and the Python package installer (pip). Also ensure you have Git to clone the repository.

# Prerequisites
- Python 3.11+
- pip
- git

# Clone the repository
git clone https://github.com/GPBK-STUY/treasury-mcp-os.git
cd treasury-mcp-os

# Install dependencies
pip install -e .

# Run with MCP Inspector for testing
npx @modelcontextprotocol/inspector python3 server.py

# Alternatively, connect to Claude Desktop by configuring the MCP server in claude_desktop_config.json:
# {
#   "mcpServers": {
#     "treasury-os": {
#       "command": "python3",
#       "args": ["/full/path/to/treasury-mcp-os/server.py"]
#     }
#   }
# }

Additional sections

Configuration and guardrails guide your automation. The system uses policy thresholds to flag risky conditions and to decide when to surface explicit recommendations. You’ll configure or adjust these guardrails to match your organization’s credit and treasury standards, such as minimum DSCR, current ratio, leverage, and covenant headroom. You can also set operating reserve levels and runway thresholds to ensure you do not run cash too close to critical limits.

Extend TreasuryOS by adding a new tool. Create a new file under tools/ (for example tools/loan_analyzer.py), implement a function that returns a dictionary, and add a Pydantic model in models.py for the return type. Register it in server.py with the MCP tool decorator. You can swap in real data by changing the CSVs under sample_data/ or replacing CSV reads with API calls to Plaid, MX, or your core banking system. The tool interface stays the same.

File structure overview to help you navigate the repository shows an entry point at server.py that registers tools, a models.py for data shapes, CLAUDE.md for agent instructions, and a tools/ directory with seven tools that implement the banking logic. Sample data includes accounts.csv, transactions.csv, vendors.csv, covenants.csv, and fx_rates.csv.

Guardrails and security notes

Use the built-in guardrails to prevent unsafe or non-compliant actions. Thresholds include: DSCR below 1.25x flags for review, current ratio below 1.20x flags for potential liquidity issues, leverage above 3.50x flags for risk, covenant headroom below 10% triggers warnings, never deploy cash below 20% of the checking balance as an operating reserve, and runway below 90 days escalates with greater urgency, with below 30 days prompting immediate action. Early payments are recommended only when the annualized return exceeds 10% against your cost of capital.

Security and data handling should follow your organization’s policies for financial data. When you swap in real client data, ensure access is restricted to authorized personnel and that data sources comply with your internal risk and privacy requirements.

Notes on data sources and data flow

The data layer currently reads CSV files in sample_data/ for demonstration. Tomorrow, you can swap to live bank APIs while keeping the same tool logic, so the tools don’t change even as the data source evolves.

Available tools

Cash Position Aggregator

Aggregates balances from all accounts, categorizes by currency and account type, and presents a consolidated starting point for treasury conversations.

Idle Cash Detector

Identifies cash above operating reserves that is earning below-market rates and estimates annual lost yield.

Cash Flow Forecaster

Analyzes three months of transactions, computes weekly category averages, and projects cash flow 90 days forward with confidence estimates.

Working Capital Analyzer

Calculates DSOs, DPOs, cash conversion cycle, current ratio, and runway days to provide a health assessment for credit reviews.

Payment Timing Optimizer

Evaluates vendor discounts and computes annualized returns for early payments to determine whether discounts are financially advantageous.

FX Exposure Scanner

Detects non-USD payables, converts them to USD, and computes Value at Risk to reveal unhedged FX exposure.

Debt Covenant Monitor

Tracks covenants across facilities, computes headroom percentages, and flags warnings or breaches.