MCP Mifosx Self Service

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:

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

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

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

3. 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:

| MIFOS_USERNAME | Self-service username (optional, see below) | none | | MIFOS_PASSWORD | Self-service password (optional, see below) | none | | MIFOS_STEP_UP_CHANNEL | EMAIL or SMS: where the verification code is sent (see below) | first channel the bank offers | | MIFOS_STEP_UP_ALLOW_CHAT_OTP | false to forbid typing the code in the chat (see below) | true |

Authentication

Tools do not take a username or password. The server keeps the login itself, so the AI never sees the password or the access token. There are two ways to log in:

1. Recommended: set MIFOS_USERNAME and MIFOS_PASSWORD in the server environment (for example in the env block of the Claude Desktop config). Tools work right away, and the password never goes through the chat.
2. Ask the assistant to call the login tool. The server keeps the access token from Fineract and returns the login details without the token. Use logout to end the session.

The session lives in the server process. This is safe for the default stdio transport (one server per user); do not share one server between several users.

Human-in-the-loop confirmation for sensitive tools

When the bank has step-up authentication turned on (selfservice-plugin, MX-488), some operations need a one-time code that the account owner receives by e-mail or SMS: third-party transfers, transfers between your own accounts, and password changes (transfer_to_third_party, make_third_party_transfer, transfer_between_accounts, make_account_transfer, update_account_password). All other tools are unchanged.

The AI never sees the code or the one-time token the bank returns for it. The server asks for the code like this:

1. The client supports MCP elicitation (a form shown by the client). The tool shows a form such as "A verification code was sent to a***@example.com. Enter it to confirm: third-party transfer of 100.5 from account 11 to account 22." The person types the code there; it goes straight to this server and the tool finishes the transfer in the same call. A wrong code asks again (the form shows the attempts left); declining or cancelling the form stops the operation with cancelled: true and nothing is executed.
2. The client does not support elicitation. The tool answers step_up_required with a challengeId, a summary of what the code approves and the masked destination, and executes nothing. The assistant must ask you for the code and call verify_step_up(challengeId, otp). Use resend_step_up(challengeId) if the code did not arrive (the bank limits how soon and how often). Typing the code in the chat means the code passes through the AI client and its logs: it is a one-time code that is tied to that one operation, but if you do not accept that, set MIFOS_STEP_UP_ALLOW_CHAT_OTP=false. Then, without elicitation, no code is sent at all and the tool tells the user to confirm in the bank's own app or website.

The request that runs after the code is accepted is the one that was approved. The server keeps it (it is not read from the AI again), and the bank also ties the code to the accounts and the amount, so the AI cannot approve one operation and run another. A waiting operation is kept in memory for 10 minutes and for at most 5 operations.

Step-up needs a login session: call login. Credentials from MIFOS_USERNAME / MIFOS_PASSWORD alone are not enough for this step (the bank answers session.required and the tool says so). MIFOS_STEP_UP_CHANNEL picks SMS or e-mail when the user has both; if that channel is not available the first one the bank offers is used.

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",
        "MIFOS_USERNAME": "your-username",
        "MIFOS_PASSWORD": "your-password"
      }
    }
  }
}

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:

• Log in (only needed if MIFOS_USERNAME / MIFOS_PASSWORD are not set)
• 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

Transfers

License

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