Mifos

The Mifos MCP server enables AI agents to securely access and operate on financial data within the Mifos X ecosystem. It provides a standardized Model Context Protocol interface that you can run locally or connect to remotely, allowing agents to query data, create and manage entities, and perform common workflows through a consistent API surface.

How to use

You interact with the MCP server through an MCP client that supports STDIO or SSE transports. Start the server locally and then connect your client using the STDIO transport for a lightweight, self-contained workflow. You can test capabilities such as creating clients, applying for loans, and performing transactions by issuing MCP requests from your client and receiving structured responses.

How to install

Prerequisites you need on your machine before starting are a Java development environment (JDK 21+), and Maven. You will also use a lightweight runner to start the MCP server from sources.

# Prerequisites
# Ensure JDK 21+ is installed
java -version

# Maven wrapper is included in the project
./mvnw -v

# Start the MCP server quickly using the provided runner
# Option 1: Run via JBang for a quick start
jbang --quiet org.mifos.community.ai:mcp-server:1.0.0-SNAPSHOT:runner

# Option 2: Build a native/runtime executable after dependencies are resolved
./mvnw package -Dnative
./target/mcp-server-1.0.0-SNAPSHOT-runner

Optional steps to produce a native executable for production-style runs are shown above; you can choose the approach that fits your environment.

## Additional configuration and usage notes

Configure the connection to your Fineract/MifosX instance using environment variables in your shell or IDE before starting the MCP server. The following variables are required to access the remote data source:

export FINERACT_BASE_URL="https://your-fineract-instance" export FINERACT_BASIC_AUTH_TOKEN="your_api_token" export FINERACT_TENANT_ID="default"

# Note
# Java-based deployments commonly use the MIFOSX_ prefixed environment variables as aliases for these values
export MIFOSX_BASE_URL="https://your-fineract-instance"
export MIFOSX_BASIC_AUTH_TOKEN="your_api_token"
export MIFOS_TENANT_ID="default"

Testing with MCP Inspector

To verify your MCP server is reachable and behaving as expected, you can use the MCP Inspector tool. It provides a web-based UI and connects to your server over STDIO or SSE.

npx @modelcontextprotocol/inspector

This starts a local web UI. In the inspector, connect to your MCP server using the STDIO transport. Ensure your MCP server is running before you start the inspector.

## Examples and workflows

You can perform end-to-end workflows such as creating a client, applying for a loan, approving and disbursing funds, and recording repayments. Each action is executed through MCP requests issued by your agent or client tooling, and responses are returned in structured data suitable for agent reasoning.

## Available tools

### MCP Inspector

A web-based UI to test, debug, and interact with your MCP server by connecting over STDIO or SSE.