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*.xmlindir_xml, produces one PDF per XML inout_dir, and writesmanifest.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
git clone <REPO_URL>
cd <REPO_DIR>
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Create your environment file (use absolute WSL paths):
cp .env.example .env
Key variables used by the server (placeholders shown):
# I/O
FEL_XML_PATH=/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml
FEL_OUTPUT_PDF=/ABSOLUTE/PATH/TO/REPO/data/out/factura.pdf
FEL_BATCH_OUT_DIR=/ABSOLUTE/PATH/TO/REPO/data/out
# optional logo
FEL_LOGO_PATH=/ABSOLUTE/PATH/TO/REPO/data/logos/logo.jpg
# Fonts
FEL_ACTIVE_FONT=1
FEL_FONT_DIR_MONTSERRAT=/ABSOLUTE/PATH/TO/REPO/assets/fonts/Montserrat/static
FEL_FONT_DIR_ROBOTOMONO=/ABSOLUTE/PATH/TO/REPO/assets/fonts/Roboto_Mono/static
# Theme/Layout
FEL_THEME=light
FEL_QR_SIZE=150
FEL_TOP_BAR_HEIGHT=20
▶️ Run the server (STDIO)
source venv/bin/activate
python servers/fel_mcp_server/server_stdio.py
🧪 Quick CLI tests (JSON-RPC over stdin)
List tools:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| python servers/fel_mcp_server/server_stdio.py
Validate one XML:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_validate","arguments":{"xml_path":"/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml"}}}' \
| python servers/fel_mcp_server/server_stdio.py
Render one PDF (no logo):
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_render","arguments":{"xml_path":"/ABSOLUTE/PATH/TO/REPO/data/xml/factura.xml","out_path":"/ABSOLUTE/PATH/TO/REPO/data/out/testing.pdf"}}}' \
| python servers/fel_mcp_server/server_stdio.py
Batch:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"fel_batch","arguments":{"dir_xml":"/ABSOLUTE/PATH/TO/REPO/data/xml","out_dir":"/ABSOLUTE/PATH/TO/REPO/data/out/batch"}}}' \
| python servers/fel_mcp_server/server_stdio.py
🖥️ Use with Claude Desktop (MCP)
-
Install Claude Desktop: https://claude.ai/download
-
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.
- Use absolute WSL paths in
-
Restart Claude Desktop (PowerShell):
Stop-Process -Name "Claude" -Force; Start-Process "<ABSOLUTE_WINDOWS_PATH_TO_Claude.exe>"