easypaydirect-mcp

Purpose

easypaydirect-mcp is an unofficial, read-only Model Context Protocol (MCP) server for accessing the Query API of the Easy Pay Direct (EPD) / NMI family of payment gateways. It enables AI assistants (Claude Desktop, Claude Code, or any MCP client) to securely and read-only query transactions, subscriptions, recurring plans, and Customer Vault records in the gateway, so they can ask questions in natural language, such as "find the failed transactions for this customer last week" or "is this subscription still active."

Easy Pay Direct is built on the NMI / Network Merchants gateway platform, so this server is also suitable for any NMI white-label gateway—just point it at your gateway host. EPD is merely a typical example, not the upper limit of its applicability.

Project statement: This project is not affiliated with, endorsed by, or sponsored by Easy Pay Direct or NMI. "Easy Pay Direct," "EPD," and "NMI" are trademarks of their respective owners. This is an independent open-source client for their public Query API.

Main capabilities

• Read-only queries: The server communicates only with the gateway's Query API (/api/query.php, the reporting endpoint). There is no code path to the transaction endpoint (transact.php), so it cannot charge, refund, void transactions, or modify the Vault. An LLM connected to this server can only view, not touch funds. For security details, see docs/security.md.
• Covered objects: transactions, subscriptions, recurring plans, Customer Vault records.
• Broad compatibility: Suitable for any NMI white-label gateway, requiring it to be pointed at the corresponding gateway host.

Usage

Runtime environment and configuration:

• Requires Node.js 18+.
• The server uses the MCP protocol over stdio and requires two environment variables.
• For instructions on how to find the key and host, see docs/configuration.md.

Running with Docker:

No local Node.js required. Build the image from the repository root, then use -i Run — MCP communicates over stdio, so the container needs to keep stdin open. You can also put variables in an env file (--env-file .env). .env is already git-ignored — never commit real secrets.

Connect to Claude:

Claude Desktop — add to claude_desktop_config.json (see examples/claude-desktop-config.json). To use the Docker image instead, replace the command — a bare -e NAME forwards the variable into the container. See docs/getting-started.md for the full tutorial.

Claude Code plugin (server + skill):

The plugin installs the MCP server and an Agent Skill that teaches Claude how to read gateway data correctly — for example, a successful ACH sale is only submitted, not paid, and EPD timestamps are in UTC. Set the secret in your shell (the plugin reads it from the environment variable), then install. Using another client? The skill is just a plain SKILL.md that can be added to any tool that supports Agent Skills.

Tool notes:

All tools are read-only. See docs/tools.md for the full reference. You can run it locally against MCP Inspector. See docs/nmi-api-mapping.md for the architecture and how the tools map to the Query API.

When to use it

• Query a customer's failed transactions from last week in natural language.
• Confirm whether a subscription is still active.
• Look up reporting data such as transactions, subscriptions, recurring plans, and Customer Vault records.

Limitations and boundaries

• Strictly read-only: cannot charge, refund, void transactions, or modify the Vault. Write operations may be offered in a future major version — always opt-in, off by default, and explicitly scoped.
• Requires Node.js 18+, communicates over stdio.
• Only targets the Query API of NMI-series gateways.
• Not officially affiliated with Easy Pay Direct or NMI.

Planned / under consideration (contributions welcome, see open issues):

• Testing —A unit test suite using recorded Query API fixtures (#1)
• Friendlier dates — accept ISO-8601 in date filters (#2)
• More filters — merchant custom fields on search_transactions (#3)
• Better errors — map NMI response codes to actionable error messages (#4)
• Distribution — auto-publish on release (#8)
• Documentation — response field reference (#9)

Read-only remains the default posture — any write support will be a separate, opt-in, scoped major version. See the changelog for released changes. License: MIT © the easypaydirect-mcp contributors. Documentation at:https://praveendias1180.github.io/easypaydirect-mcp/