Mifosx

🚀 Apache Fineract API MCP Server

This project provides a Model Context Protocol (MCP) server for the Apache Fineract API, enabling AI agents to access financial data and operations. It offers implementations in Python, Java (Quarkus), and Node.js.

🚀 Quick Start

1. Choose an Implementation

Python (Flask)

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

Steps:

1. Install dependencies:

   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. Quickly run with JBang:

   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 using the built - in inspect script:

   npm run inspect
   

✨ Features

• Standardized API Access via fineract:// URIs
• MCP Compliance Supports STDIO/SSE transports
• Environment Independence Flexible configuration

📦 Installation

MCP Development Tools

Use the MCP Inspector to test and debug your server:

npx @modelcontextprotocol/inspector

This launches a local Web UI that connects to your MCP server via STDIO or SSE.

💻 Usage Examples

Using the MCP Inspector for Testing

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.

📚 Documentation

Configuration

All implementations require the following environment variables:

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

Available Resources

The MCP server exposes the following resources:

Core Resources

• fineract://clients
  List all clients
• fineract://clients/{clientId}
  Get detailed information about a specific client
• fineract://loans
  List all loans
• fineract://loans/{loanId}
  Get detailed information about a specific loan

Tools

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

Building a Native Executable (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

Contribution Guide

• Python: Modify python/app.py and configure the .env file path.
• Java: Configure environment variables in src/main/java/org/mifos-community/ai/MCPServer.java.
• Node.js: Edit config.js to set server parameters.