MifosX Self Service MCP

March 4, 2026 · View on GitHub

MifosX Self Service MCP is a Model Context Protocol (MCP) server built using FastMCP (Python). It exposes a set of AI-callable tools that allow MCP-compatible clients (such as Claude Desktop or DeepChat) to securely interact with the Apache Fineract / MifosX Self-Service APIs.

This project enables AI-driven banking workflows such as authentication, account access, beneficiary management, loans, savings, and transfers — while keeping all sensitive logic on the server side.

Features

Register new self-service users.
Confirm user registration.
User login and authentication.
Manage client information.
Manage beneficiaries (add, list, update, delete).
View client accounts and transactions.
Manage loans (view products, applications, transactions, charges).
Manage savings accounts (products, applications, transactions, charges).
Manage guarantors for loans.
Manage share accounts and products.
Register for push notifications.
Perform third-party account transfers.

Architecture

The MCP server acts as a secure bridge between your AI client and the Mifos/Fineract backend.

graph LR
    A[AI Client] -- MCP Protocol --> B[FastMCP Server]
    B -- REST API --> C[MifosX / Fineract]
    C -- Data --> B
    B -- Context --> A

Project Structure

The codebase is organized into a modular, maintainable structure:

mcp-mifosx-self-service/
│
├── main.py              # MCP server entry point
├── mcp_app.py           # FastMCP app initialization
│
├── config/
│   └── config.py        # Environment-based configuration
│
├── routers/             # MCP tools grouped by domain
│   ├── auth_tools.py        # User registration & authentication
│   ├── client_tools.py      # Client information & accounts
│   ├── beneficiary_tools.py # Beneficiary management
│   ├── transfer_tools.py   # Third-party transfers
│   ├── loan_tools.py        # Loan products & accounts
│   ├── savings_tools.py     # Savings accounts & products
│   ├── guarantor_tools.py  # Loan guarantor management
│   ├── shares_tools.py     # Share accounts & products
│   └── notification_tools.py # Push notification registration
│
├── schemas/             # Pydantic request/response models
│   ├── registration.py
│   ├── authentication.py
│   ├── confirm.py
│   ├── beneficiary.py
│   └── transfer.py
│
├── utils/               # Shared helpers
│   ├── http.py          # Centralized HTTP client
│   └── auth.py          # Auth helpers (Basic Auth)
│
├── resources/           # MCP resources (context & docs)
│   ├── overview.py
│   ├── endpoints.py
│   └── workflows.py
│
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── README.md

Installation

Clone the repository:

git clone https://github.com/openMF/mcp-mifosx-self-service.git
cd mcp-mifosx-self-service

Create and activate a virtual environment (recommended):

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the required dependencies:
```
pip install -r requirements.txt
```

Configuration

The application connects to a Fineract API. Use environment variables (or a .env file) for customization:

Variable	Description	Default
`MIFOS_BASE_URL`	Base URL of Fineract instance	`https://tt.mifos.community`
`MIFOS_TENANT`	Tenant identifier	`default`

For authentication, the application uses default credentials (maria/password), but these can be overridden using environment variables for better security and flexibility.

Running with Docker

The project includes Docker support for easy deployment:

# Build and run with docker-compose
docker-compose up --build

Using with Claude Desktop (MCP)

In Claude Desktop → Settings → Developer → Local MCP servers → Edit Config, add:

{
  "mcpServers": {
    "mifos-banking": {
      "command": "/ABSOLUTE/PATH/TO/venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/main.py"
      ],
      "env": {
        "MIFOS_BASE_URL": "https://tt.mifos.community",
        "MIFOS_TENANT": "default"
      }
    }
  }
}

Restart Claude Desktop after saving.

Running the Server

To run the MCP server, execute the following command from the project's root directory:

python3 main.py

Example Usage (Natural Language) on Claude

Once the MCP server is connected, Claude can invoke the available tools automatically. You can paste the following prompts in Claude Desktop to verify that your configuration is working correctly:

Login using username maria and password password
Get my client information
Show my client accounts
List my beneficiaries
Get my loan accounts
Show my savings accounts

If these commands return valid responses, your MCP server is successfully connected and operational.

Available MCP Tools

The MCP server exposes the following AI-callable tools. Each tool internally maps to a Fineract self-service API call. These tools are invoked by MCP-compatible AI clients, not directly via HTTP.

Authentication

Method	MCP Tool Name	Description
POST	`register_self_service`	Register a new self-service user
POST	`confirm_registration`	Confirm user registration with token
POST	`login_self_service`	Authenticate a self-service user

Client & Accounts

Method	MCP Tool Name	Description
GET	`get_client_info`	Retrieve client information
GET	`get_client_accounts`	Retrieve client accounts
GET	`get_client_charges`	Retrieve client charges
GET	`get_client_transactions`	Retrieve client transactions

Beneficiaries

Method	MCP Tool Name	Description
GET	`get_beneficiaries`	List all beneficiaries
GET	`get_beneficiary_template`	Get beneficiary template for an account
POST	`add_beneficiary`	Add a new beneficiary
PUT	`update_beneficiary`	Update an existing beneficiary
DELETE	`delete_beneficiary`	Delete a beneficiary

Loans

Method	MCP Tool Name	Description
GET	`get_loan_products`	Retrieve available loan products
GET	`get_loan_product_details`	Retrieve loan product details
GET	`get_loan_account_details`	Retrieve loan account details
GET	`get_loan_transaction_detail`	Retrieve loan transaction detail
GET	`get_loan_account_charges`	Retrieve loan charges
GET	`get_loan_template`	Retrieve loan application template
POST	`calculate_loan_repayment_calendar`	Calculate loan repayment schedule
POST	`submit_loan_application`	Submit loan application
PUT	`update_loan_application`	Update loan application
POST	`withdraw_loan_application`	Withdraw loan application

Savings

Method	MCP Tool Name	Description
GET	`get_savings_products`	Get list of savings products
GET	`get_savings_product_details`	Get savings product details
GET	`get_savings_account_details`	Get savings account details
GET	`get_savings_account_transactions`	Get savings account transactions
GET	`get_savings_account_transaction_details`	Get transaction details
GET	`get_savings_account_charges`	Get savings account charges
GET	`get_savings_account_template_raw`	Get savings account template
POST	`submit_savings_application`	Submit savings account application
PUT	`update_savings_account_application`	Update savings account application

Guarantors

Method	MCP Tool Name	Description
GET	`get_guarantor_template`	Get template for creating guarantors
GET	`get_guarantor_list`	Get list of guarantors for a loan
POST	`create_guarantor`	Add a new guarantor for a loan
PUT	`update_guarantor`	Update an existing guarantor
DELETE	`delete_guarantor`	Delete a loan guarantor

Method	MCP Tool Name	Description
GET	`get_share_product_list`	Get list of share products
GET	`get_share_product_details`	Get share product details

Notifications

Method	MCP Tool Name	Description
GET	`get_user_notification_details`	Get notification registration details
POST	`register_for_notifications`	Register device for push notifications
PUT	`update_notification_registration`	Update notification registration

Transfers

Method	MCP Tool Name	Description
GET	`get_transfer_template`	Retrieve transfer options
POST	`make_third_party_transfer`	Perform a third-party account transfer

License

This project is licensed under the terms included in the LICENSE file.