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.

• Read account statements and spending insights (statement, summary, recurring payments).

• Register for push notifications.

• Perform third-party account transfers.

Related MCP server: Griffin MCP server

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
│   ├── statement_tools.py   # Statements, spending summary, recurring payments
│   ├── 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, SMS or TOTP: how the verification code reaches the user (see below) | the authenticator app if the user paired one, otherwise the first channel the bank offers | | MIFOS_STEP_UP_ALLOW_CHAT_OTP | false to forbid typing the code in the chat (see below) | true | | MIFOS_TRANSFER_MAX_AMOUNT | Largest transfer the assistant may prepare; larger ones must be made in the bank's app | no limit | | MIFOS_TRANSFER_CONFIRM_TTL_SECONDS | How long a prepared transfer can be confirmed | 300 | | MIFOS_TIMEZONE | The bank's time zone (e.g. America/Mexico_City), used for the transfer date | server's time zone |

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.

Transfers: prepare, then confirm

The assistant cannot move money in one call. Every transfer takes two tools:

1. prepare_transfer(from_account_id, to_account_id, amount, description, ...) moves no money. It checks that the source is one of your accounts and that the destination is one of your own accounts (for example a loan, for a repayment) or, with third_party: true, one of your saved beneficiaries. It checks the amount against MIFOS_TRANSFER_MAX_AMOUNT and the available balance, and returns a summary (accounts, amount, currency, fee) with a confirmation_id. The assistant shows you the summary and asks you to confirm.

2. confirm_transfer(confirmation_id) sends exactly the request that was prepared. The server keeps it, so the AI cannot change the accounts or the amount in between. The id works once and expires after MIFOS_TRANSFER_CONFIRM_TTL_SECONDS (5 minutes by default; at most 5 prepared transfers are kept). If your client supports MCP elicitation, it also shows you a form ("Send this ... ?") and nothing is sent unless you confirm there (if the form cannot be shown, nothing is sent either). If the bank asks for a one-time code, the confirmation continues as described below.

cancel_transfer(confirmation_id) drops a prepared transfer.

Applying for shares works the same way: prepare_share_application (checks the product's share limits and that the linked savings account is the client's, active and in the product's currency, and returns the total price), then confirm_share_application or cancel_share_application. A share confirmation id cannot confirm a transfer, and the other way round. The bank still has to approve the application.

Adding a beneficiary works the same way, because money can be sent to it later: prepare_beneficiary(name, account_number, office_name, account_type, transfer_limit) checks the account type ("savings" or "loan") against the bank's template and the office against the bank's offices, takes the currency of your own accounts (or the currency you pass) and saves nothing. prepare_beneficiary_change(beneficiary_id, name, transfer_limit) shows the old and new values; the bank only lets the name and the transfer limit change. confirm_beneficiary saves either one, cancel_beneficiary drops it.

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 (confirm_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.

Authenticator app

If the bank also offers an authenticator app (Google Authenticator, Microsoft Authenticator...) and the user paired one, the verification uses it (channel TOTP): nothing is sent, the person types the 6-digit code the app shows now. By default the bank offers only the app to such a user (so an intercepted SMS is of no use), and this server then uses it without any setting.

• With elicitation the form asks for "Code from your authenticator app" and, only for a lost phone, "Recovery code" (one of the codes the user saved when pairing; each works once). The form takes one of the two. A wrong code asks again, as before.

• Without elicitation the chat fallback accepts only the 6-digit code of the app, which is valid for seconds and for this one operation. A recovery code is never accepted in the chat (it is a long-lived credential); the tool tells the user to use a client with elicitation or the bank's own app. resend_step_up does not apply: an app code cannot be sent again.

• Pairing, new recovery codes and removing the app are not tools. The secret and the recovery codes must not pass through an AI conversation, so the user does that in the bank's own app or website.

Errors

When the bank refuses a request, tools answer with a short, readable error instead of the bank's raw response:

{"error": true, "status_code": 400,
 "message": "The parameter `productId` is mandatory.",
 "errors": [{"message": "The parameter `productId` is mandatory.", "parameter": "productId"}],
 "code": "validation.msg.validation.errors.exist"}

errors lists the fields to fix and code is the bank's error code. Developer messages, server paths and HTML error pages are never passed on.

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

Loan applications take typed fields (product, amount, number of repayments, loan purpose, expected disbursement date). Everything else (interest, repayment frequency, product charges) comes from the bank's loan template, and the amount and number of repayments are checked against the product's limits. A loan creates a debt, so prepare_loan_application returns the schedule the bank calculates and submits nothing; confirm_loan_application submits it only with the confirmation id, at most once, and asks the person in a form when the client can show one. Passing loan_id changes an application that is still waiting for approval the same way.

Loan simulation (no login needed)

Savings

Statements & Insights

Read-only tools that reshape a savings account's own transaction list into a statement and spending picture. Everything is computed by the MCP server from the bank's rows — see the "Honest limits" line in each tool's description.

Guarantors

Shares

Notifications

Offices

Profile and pockets

Transfers

License

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