Mifos X

What is mcp-mifosx?

mcp-mifosx is a project that offers Model Context Protocol (MCP) servers designed to facilitate interaction with the Apache Fineract API. This allows AI agents to securely access and manage financial data and operations within the Mifos X open-source banking platform.

How to use mcp-mifosx?

mcp-mifosx provides implementations in Python (Flask), Java (Quarkus), and Node.js. To use it, you need to:

1. Choose your implementation: Select the language and framework you prefer.
2. Install prerequisites: Ensure you have the necessary dependencies (e.g., Python 3.8+, JDK 17+, Node.js 16+).
3. Configure environment variables: Set FINERACT_BASE_URL, FINERACT_BASIC_AUTH_TOKEN, and FINERACT_TENANT_ID (Java uses MIFOSX_ prefixes).
4. Run the server: Execute the appropriate command for your chosen implementation (e.g., mcp dev app.py for Python, jbang --quiet org.mifos.community.ai:mcp-server:1.0.0-SNAPSHOT:runner for Java, npm run dev for Node.js).
5. Test with MCP Inspector: Use npx @modelcontextprotocol/inspector to test and debug your server via a local web UI.

Key Features of mcp-mifosx

• Standardized API access: Provides a consistent way to access financial data using fineract:// URIs.
• MCP-compliant: Adheres to the Model Context Protocol, supporting STDIO/SSE transports.
• Multi-language support: Available in Python, Java, and Node.js, offering flexibility for developers.
• Environment-agnostic configuration: Easy to configure across different environments.
• Resource exposure: Exposes core resources like clients and loans, and tools for searching clients, creating clients (Node.js/Python), and updating loan status (Java/Python).

Use Cases of mcp-mifosx

• AI-driven financial management: Enables AI agents to interact with Mifos X for tasks like managing clients, loans, savings, and financial transactions.
• Automated financial reporting: Allows AI to generate financial reports by accessing data through the Fineract API.
• Integration with AI applications: Provides a bridge for AI applications to leverage the functionalities of Apache Fineract.
• Developing custom financial tools: Developers can build custom tools and applications that interact with Mifos X using the MCP servers.

FAQ about mcp-mifosx

• What is Apache Fineract? Apache Fineract is an open-source core banking platform.
• What is Model Context Protocol (MCP)? MCP is a protocol that allows AI agents to interact with various services and data sources in a standardized way.
• Which programming languages are supported? Python, Java, and Node.js.
• How do I configure the server? You need to set environment variables for the Fineract base URL, API token, and tenant ID.
• Can I build a native executable for Java? Yes, you can build a native executable using Maven with the -Dnative flag.
• How can I test my MCP server? You can use the MCP Inspector by running npx @modelcontextprotocol/inspector and connecting to your server.

Mifos X - AI - Model Context Protocol (MCP) for Apache Fineract®

This project provides Model Context Protocol (MCP) servers for interacting with the Apache Fineract API, enabling AI agents to access financial data and operations. Implementations are available in Python, Java (Quarkus), and Node.js.

---

MCP Developer Tools

Use the MCP Inspector to test and debug your server:

npx @modelcontextprotocol/inspector

This starts a local web UI to connect to your MCP server via STDIO or SSE.

---

Getting Started

1. Choose Your Implementation

Python (Flask)

Prerequisites: Python 3.8+, flask, mcp.server.fastmcp

Steps:

1. Install dependencies:

   pip install mcp[cli] uv flask
   

   Note for zsh users: If you're using zsh, be sure to quote extras to avoid shell expansion errors:

   pip install 'mcp[cli]' uv flask
   

2. Run the server:

   mcp dev app.py
   

Java (Quarkus)

Prerequisites: JDK 17+, Maven

Steps:

1. Configure environment variables in your shell or IDE:

   export MIFOSX_BASE_URL="https://your-fineract-instance"
   export MIFOSX_BASIC_AUTH_TOKEN="your_api_token"
   export MIFOS_TENANT_ID="default"
   

2. Run via JBang (for quick execution):

   jbang --quiet org.mifos.community.ai:mcp-server:1.0.0-SNAPSHOT:runner
   

3. (Optional) Build a native executable:

   ./mvnw package -Dnative
   ./target/mcp-server-1.0.0-SNAPSHOT-runner
   

Node.js

Prerequisites: Node.js 16+, npm

Steps:

1. Install dependencies:

   cd nodejs && npm install
   

2. Configure environment variables in .env:

   cp .env.example .env
   

3. Run the server:

   npm run dev
   

4. Test with the built-in inspect script:

   npm run inspect
   

---

Configuration

All implementations require the following environment variables:

Variable	Description
FINERACT_BASE_URL	Base URL of your Fineract instance
FINERACT_BASIC_AUTH_TOKEN	API authentication token
FINERACT_TENANT_ID	Tenant identifier (default: default)

Note: Java uses MIFOSX_ prefixed variables (e.g., MIFOSX_BASE_URL).

---

Available Resources

The MCP server exposes these resources:

Core Resources

• fineract://clients
  List all clients
• fineract://clients/{clientId}
  Get details for a specific client
• fineract://loans
  List all loans
• fineract://loans/{loanId}
  Get details for a specific loan

Tools

• search_clients
  Search clients by name/attributes
• create_client
  Create a new client (Node.js/Python only)
• update_loan_status
  Update loan status (Java/Python only)

---

Building Native Executables (Java Only)

For Java (Quarkus), create a native executable:

./mvnw package -Dnative -Dquarkus.native.container-build=true
./target/mcp-server-1.0.0-SNAPSHOT-runner

---

Testing with MCP Inspector

1. Start your MCP server (Python/Java/Node.js).
2. Run the inspector:

   npx @modelcontextprotocol/inspector
   

3. Connect to the server using the STDIO transport.

---

Contributing

• Python: Modify python/app.py and server.js for new resources.
• Java: Extend src/main/java/org/mifos/community/ai/... for new endpoints.
• Node.js: Update nodejs/src/server.js and add Zod schemas for validation.

---

Contact

• Apache Fineract Community: https://community.apache.org/
• MCP Specification: https://modelcontextprotocol.org

---

Guides

• Java/Quarkus: Quarkus MCP Guide
• Node.js: Use npm run inspect for live reloading
• Python: Run with python app.py and configure .env

---

Key Features:

• Standardized API access via fineract:// URIs
• MCP-compliant with STDIO/SSE transports
• Environment-agnostic configuration