FEL MCP Server (Local)

Local Model Context Protocol (MCP) server for Guatemalan FEL invoices.
Exposes tools to validate FEL XML and render branded PDFs. Designed for WSL (Ubuntu) or Linux and can be consumed by MCP hosts (e.g., Claude Desktop).

This repository focuses on the FEL MCP server. It’s often used alongside a chatbot client; see “Related repositories”.

🔗 Related repositories

• Chatbot (CLI / UI) — client that can drive this MCP server.

• Reference: OpenAI Chat API Example — reference only (patterns for API connectivity and instruction context).

✨ Tools (MCP)

• fel_validate
  required: xml_path (absolute WSL path)
  Checks required fields and totals (subtotal, VAT 12%, total).

• fel_render
  required: xml_path, out_path (absolute WSL paths)
  Renders a branded PDF from the FEL XML.

• fel_batch
  required: dir_xml, out_dir (absolute WSL paths)
  Processes all *.xml in dir_xml, produces one PDF per XML in out_dir, and writes manifest.json.

Use absolute WSL paths like /mnt/d/... in all arguments and environment variables.

⚙️ Requirements

• Python 3.12

• WSL Ubuntu 22.04 (or Linux)

• Virtual environment (recommended)

🔧 Installation

Create your environment file (use absolute WSL paths):

Key variables used by the server (placeholders shown):

▶️ Run the server (STDIO)

🧪 Quick CLI tests (JSON-RPC over stdin)

List tools:

Validate one XML:

Render one PDF (no logo):

Batch:

🖥️ Use with Claude Desktop (MCP)

1. Install Claude Desktop: https://claude.ai/download

2. Open Settings -> Developer -> Edit Config, then edit claude_desktop_config.json:

   { "mcpServers": { "FEL": { "command": "wsl.exe", "args": [ "-e", "/ABSOLUTE/PATH/TO/REPO/venv/bin/python", "/ABSOLUTE/PATH/TO/REPO/servers/fel_mcp_server/server_stdio.py" ] } } }

   • Use absolute WSL paths in args.

   • If the host logs show errors like "'xml_path'", it means the call was sent without arguments; re-run with a prompt that includes the exact JSON arguments block.

3. Restart Claude Desktop (PowerShell):

📚 References

• Model Context Protocol

• Anthropic API

• JSON-RPC 2.0