Mcp-Ksef

This MCP server implements access to the KSeF (Krajowy System e-Faktur) platform. It currently supports retrieving invoices via token-based or certificate-based authentication. The server exposes endpoints corresponding to the actions described in the project docs, such as fetching a single invoice by KSeF number, listing invoices for a period, retrieving invoices by buyer Nip or VAT, and obtaining invoice URLs or QR codes. Use the MCP client tooling to invoke these endpoints by name, for example invoking a command like get_invoice_by_invoice_number with a specific invoice reference, or using the predefined examples in the Docs to perform common tasks. The README and Docs provide concrete endpoint names such as get_invoice_by_ksef, get_invoices_for_period, get_invoice_by_invoice_number, get_invoices_for_buyer_by_nip, get_invoices_for_buyer_by_vateu, get_invoice_url_by_ksef, and get_invoice_qr_ksef. The server will require either a valid token or a configured certificate to access KSeF resources, so ensure your credentials are supplied via environment variables when starting the container. You can also inspect the included Docs/Installation.md and Docs/Examples.md for practical usage scenarios and sample commands.

Prerequisites:

• Docker installed on your system (Docker Desktop for Windows/macOS or Docker Engine for Linux).
• Internet access to pull the MCP-KSeF Docker image and communicate with KSeF.

Steps:

1. Install Docker on your machine following the official guidelines for your OS.
2. Pull and run the MCP-KSeF image with required credentials:

# Pull the image
docker pull herbat73/mcp-ksef

# Run the container with environment variables (adjust as needed)
docker run -i \
  -e KSEF_TOKEN="<insert_token_here>" \
  -e KSEF_CERT_PATH="/path/to/cert" \
  -e KSEF_CERT_PASSWORD="<cert_password>" \
  -e MCP_PORT="8080" \
  -p 8080:8080 \
  herbat73/mcp-ksef

3. If you prefer using a token or certificate, supply the appropriate environment variables as shown above. The server will listen on the port you expose (default 8080). You can also start the image with a different port by adjusting MCP_PORT and the -p mapping accordingly.
4. Verify connectivity and consult Docs/Endpoints.md for the available MCP endpoints and usage examples.

Notes and tips:

• The MCP server currently focuses on retrieving invoices from KSeF; additional features will be added over time.
• Use token-based or certificate-based authentication as required by your KSeF integration; ensure credentials are kept secure and not committed to source.
• If you encounter connection issues to KSeF, verify network access and that the environment variables (token, cert path) are correctly configured.
• The container image name is herbat73/mcp-ksef; refer to the DockerHub page for details and latest tags. If you run into port conflicts, change MCP_PORT and map accordingly when starting the container.
• For troubleshooting, check container logs for any authentication or endpoint errors, and consult the Docs folder for endpoint references and usage examples.