MifosX Self Service MCP

1# MifosX Self Service MCP
2 
3MifosX Self Service MCP is a Model Context Protocol (MCP) server built using FastMCP (Python).
4It 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.
5 
6This project enables AI-driven banking workflows such as authentication, account access, beneficiary management, and transfers — while keeping all sensitive logic on the server side.
7 
8## Features
9 
10*   Register new self-service users.
11*   Confirm user registration.
12*   User login and authentication.
13*   Manage client information.
14*   Manage beneficiaries (add, list, update, delete).
15*   View client accounts and transactions.
16*   Perform third-party account transfers.
17 
18## Project Structure
19 
20```text
21The codebase is organized into a modular, maintainable structure:
22 
23mcp-mifosx-self-service/
24│
25├── main.py              # MCP server entry point
26├── mcp_app.py           # FastMCP app initialization
27│
28├── config/
29│   └── config.py        # Environment-based configuration
30│
31├── routers/             # MCP tools grouped by domain
32│   ├── auth_tools.py
33│   ├── client_tools.py
34│   ├── beneficiary_tools.py
35│   └── transfer_tools.py
36│
37├── schemas/             # Pydantic request/response models
38│   ├── registration.py
39│   ├── authentication.py
40│   ├── confirm.py
41│   ├── beneficiary.py
42│   └── transfer.py
43│
44├── utils/               # Shared helpers
45│   ├── http.py          # Centralized HTTP client
46│   └── auth.py          # Auth helpers (Basic Auth)
47│
48├── resources/           # MCP resources (context & docs)
49│   ├── overview.py
50│   ├── endpoints.py
51│   └── workflows.py
52│
53├── requirements.txt
54└── README.md
55 
56```
57 
58## Installation
59 
601.  **Clone the repository:**
61    ```bash
62    git clone https://github.com/openMF/mcp-mifosx-self-service.git
63    cd mcp-mifosx-self-service
64    ```
65 
662.  **Create and activate a virtual environment (recommended):**
67    ```bash
68    python3 -m venv venv
69    source venv/bin/activate
70    ```
71 
723.  **Install the required dependencies:**
73    ```bash
74    pip install -r requirements.txt
75    ```
76 
77## Configuration
78 
79The application connects to a Fineract API. The base URL and tenant ID are hardcoded in `main.py`:
80 
81*   `FINERACT_BASE_URL`: `https://tt.mifos.community/fineract-provider/api/v1`
82*   `FINERACT_TENANT_ID`: `default`
83 
84 
85## Using with Claude Desktop (MCP)
86* In Claude Desktop → Settings → Developer → Local MCP servers → Edit Config, add:
87 
88For authentication, the application uses default credentials (`maria`/`password`), but these can be overridden using environment variables for better security and flexibility.
89 
90Use this configuration file with Claude Desktop or any other IDE where you use MCP
91```bash
92{
93  "mcpServers": {
94    "tt-mobile-banking": {
95      "command": "/home/keshav/mcp-mifosx-self-service/venv/bin/python3", #your path
96      "args": [
97        "/home/keshav/mcp-mifosx-self-service/main.py" #directory where you have cloned
98      ],
99      "env": {
100        "MIFOS_BASE_URL": "https://tt.mifos.community",
101        "MIFOS_TENANT": "default"
102      }
103    }
104  }
105}
106```
107Restart Claude Desktop after saving.
108 
109## Running the Server
110 
111To run the MCP server, execute the following command from the project's root directory:
112 
113```bash
114python3 main.py
115```
116 
117## Example Usage (Natural Language) on Claude
118 
119Once the MCP server is connected, Claude can invoke the available tools automatically.
120You can paste the following prompts in Claude Desktop to verify that your configuration is working correctly:
121 
122- Login using username `maria` and password `password`
123- Get my client information
124- Show my client accounts
125- List my beneficiaries
126 
127If these commands return valid responses, your MCP server is successfully connected and operational.
128 
129## Available MCP Tools
130 
131The MCP server exposes the following AI-callable tools.
132Each tool internally maps to a Fineract self-service API call.
133These tools are invoked by MCP-compatible AI clients, not directly via HTTP.
134 
135 
136### Authentication
137 
138| Method | MCP Tool Name              | Description                              |
139|------|----------------------------|------------------------------------------|
140| POST | `register_self_service`    | Register a new self-service user          |
141| POST | `confirm_registration`     | Confirm user registration with token     |
142| POST | `login_self_service`       | Authenticate a self-service user          |
143 
144### Client & Accounts
145 
146| Method | MCP Tool Name              | Description                              |
147|------|----------------------------|------------------------------------------|
148| GET  | `get_client_info`          | Retrieve client information               |
149| GET  | `get_client_accounts`      | Retrieve client accounts                  |
150| GET  | `get_client_transactions`  | Retrieve client transactions              |
151 
152### Beneficiaries
153 
154| Method | MCP Tool Name              | Description                              |
155|------|----------------------------|------------------------------------------|
156| GET  | `get_beneficiaries`        | List all beneficiaries                    |
157| POST | `add_beneficiary`          | Add a new beneficiary                     |
158| PUT  | `update_beneficiary`       | Update an existing beneficiary            |
159| DELETE | `delete_beneficiary`     | Delete a beneficiary                      |
160 
161### Transfers
162 
163| Method | MCP Tool Name                  | Description                              |
164|------|--------------------------------|------------------------------------------|
165| GET  | `get_transfer_template`        | Retrieve transfer options                |
166| POST | `make_third_party_transfer`    | Perform a third-party account transfer   |
167