jPOS MCP Server

mcp-name: io.github.mohisyed/jpos-mcp-server

The first open-source MCP server for jPOS and ISO 8583.

Claude validating a real ISO 8583 financial transaction request using deterministic tools. No guessing — every answer comes from verified data.

An MCP server that gives AI agents (Claude, Cursor, VS Code Copilot) deterministic, verified access to ISO 8583 field specs, MTI decoding, jPOS packager XML generation, deploy descriptor validation, message building, and jPOS documentation search.

No more guessing packager class names. No more scrolling a 300-page PDF. Call a tool, get the right answer.

Table of Contents

• Quickstart
• Tools
• Architecture
• Testing
• Knowledge Base (RAG)
• Docker
• Claude Desktop Setup
• MCP Inspector
• Security
• Troubleshooting
• Roadmap
• Contributing

Quickstart

Prerequisites: Python 3.11+ and uv package manager.

# 1. Clone and install
git clone https://github.com/mohisyed/JPOS-MCP.git
cd JPOS-MCP
uv sync

# 2. (Optional) Set up the knowledge base for semantic search
mkdir -p knowledge/sources
curl -o knowledge/sources/proguide.pdf https://jpos.org/doc/proguide-draft.pdf
uv run python knowledge/ingest.py

# 3. Add to Claude Desktop (see Claude Desktop Setup below)

All 6 tools work immediately after step 1. Step 2 enables the search_jpos RAG tool with real documentation.

Tools

Why deterministic tools instead of LLM inference?

LLMs can guess that field 35 uses IFA_LLVAR, but they sometimes hallucinate class names like IFA_LLTRACK2 (doesn't exist). Our tools read from data/iso_fields.json — a verified lookup table — so the answer is always correct. The AI decides which tool to call; our code provides the facts.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      AI AGENT CLIENTS                           │
│  Claude Desktop  ·  Claude API  ·  Cursor  ·  VS Code Copilot  │
└──────────────────────────┬──────────────────────────────────────┘
                           │  MCP Protocol (JSON-RPC 2.0)
              stdio (local) / Streamable HTTP (Docker)
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│           jpos-mcp-server  (Python / FastMCP v3.1.1)            │
│                                                                  │
│  main.py                                                         │
│  ├── iso_server    [iso]   lookup_field, decode_mti              │
│  ├── jpos_server   [jpos]  genera

... [View full README on GitHub](https://github.com/mohisyed/JPOS-MCP#readme)