Achlens MCP Server

Achlens

Achlens is a local-first Python MCP server and CLI for inspecting synthetic ACH files. It parses fixed-width records, validates structure and control totals, explains findings, masks sensitive fields, repairs derived controls, and generates deterministic test files. It never transmits ACH files or makes bank/network calls.

Use synthetic data only. This project is not a bank gateway, compliance advisor, or transmission system.

Quick Start

uv sync
uv run achlens --help
uv run achlens validate tests/fixtures/golden/sample_valid.ach
uv run achlens generate --sec PPD --entries 5 --seed 7 > synthetic.ach

In Windows PowerShell, use an explicit ASCII encoding because PowerShell's default > redirection can write UTF-16 output that is not valid ACH text:

uvx achlens generate --sec PPD --entries 5 --seed 7 |
	Set-Content -Encoding ascii synthetic.ach

Run the MCP server over stdio:

uv run achlens serve

MCP Client Setup

Install the published package with uvx; it starts the server locally over stdio and does not transmit ACH files.

VS Code and Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "achlens": {
      "type": "stdio",
      "command": "uvx",
      "args": ["achlens"]
    }
  }
}

Claude Desktop

Add the following entry to the mcpServers object in Claude Desktop's MCP configuration:

{
  "achlens": {
    "command": "uvx",
    "args": ["achlens"]
  }
}

By default, MCP tools accept ACH content directly but cannot read local paths. To allow read-only access to a specific directory, set ACHLENS_ALLOWED_ROOTS in the server environment to that directory. Use synthetic ACH data only.

The MCP server exposes validation, summaries, parsed-record paging, control explanations, routing checks, code lookup, synthetic generation, and control repair. See docs/tools.md for the current tool surface.

Sensitive fields are masked by default. Configure ACHLENS_ALLOWED_ROOTS to enable MCP path inputs; otherwise provide file content directly. See SECURITY.md for the data and write boundaries.

Development

This project uses uv.

uv sync
uv run achlens --help
PYTHONPATH=. uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv run mypy --strict src

Without uv

The CLI and test suite also work with plain pip:

pip install -e . pytest
achlens --help
achlens validate tests/fixtures/golden/sample_valid.ach
achlens generate --sec PPD --entries 5 --seed 7
PYTHONPATH=. pytest

Set PYTHONPATH=. from the repository root when running tests so fixture and script imports resolve. In Windows PowerShell, use $env:PYTHONPATH = "."; pytest.

Never add real payment data, account numbers, or ACH files to this repository.