MifosX Self Service MCP

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

1. Clone the repository:

   bash

   Copy

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

2. Create and activate a virtual environment (recommended):

   bash

   Copy

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

3. Install the required dependencies:

   Terminal

   Copy

   pip install -r requirements.txt
   

Configuration

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

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

Client & Accounts

Beneficiaries

Loans

Savings

Guarantors

Shares

Notifications