MifosX Self Service MCP
openMF/mcp-mifosx-self-service
Bridge MCP seguro entre IA e plataforma bancária Fineract/MifosX
Ver no GitHubServidor MCP que expõe ferramentas de IA para interagir com APIs de auto-atendimento do Apache Fineract/MifosX. Permite fluxos bancários como autenticação, gestão de contas, beneficiários, empréstimos, poupança e transferências, mantendo lógica sensível no lado servidor.
Instalação
npx convez-ai openMF/mcp-mifosx-self-service1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de workflows bancários de auto-atendimento com IA
- Gestão programática de contas, empréstimos e poupança
- Integração de chatbots de IA com sistemas Fineract/MifosX
Veredito

Solução robusta e bem arquitetada para instituições financeiras que usam Fineract/MifosX e querem integrar capacidades de IA via MCP. Requer conhecimento técnico avançado, mas oferece segurança por design ao manter operações sensíveis no servidor.
README
A tradução para o português deste README ainda está na fila.
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
-
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
mariaand passwordpassword - 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 |
Shares
| 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.