KSeF MCP

KSeF MCP is a single-tenant Model Context Protocol server for Polish KSeF e-invoice workflows. It lets an MCP client help prepare, validate, preview, submit, and read FA(3) invoices while keeping the actual KSeF credentials and local invoice state under your control.

The default setup is local stdio for one operator. A remote HTTPS deployment is also available for services that need to expose the MCP over Streamable HTTP with external OAuth/JWKS token validation.

What It Can Do

• Check KSeF TEST readiness before any invoice write flow.

• Create, update, and validate SQLite-backed invoice drafts.

• Build and offline-validate FA(3) XML from supported standard, simplified, advance, settlement, and correction invoice drafts.

• Generate confirmation tokens before submission and enforce token expiry, production opt-in, and durable idempotency.

• Submit invoices to KSeF TEST or PROD through the guarded write path.

• List and download KSeF invoices and download UPOs.

• Render a local KSeF-like PDF preview from prepared FA(3) XML without contacting KSeF.

• Look up exchange rates from NBP and counterparties through MF VAT whitelist, VIES, KRS, and optional GUS REGON.

• Store/search local source documents and optionally use local embeddings or a local LLM for advisory extraction.

• Expose MCP resources and prompts for capabilities, schema, first-use setup, seller profile, glossary, and invoice field checklists.

• Expose ksef://first-use-checklist and the first-use-setup prompt, plus a capabilities surface that lists supported resources and terminal preflight commands.

• Ask for common primitive starter fields through bounded MCP form elicitation when a client supports it.

Related MCP server: einvoice-mcp

Current Release Status

This is a 0.1.0 release: useful for TEST-first personal and service evaluation, with production sends intentionally guarded.

Verified:

• Automated unit and smoke coverage for configuration, MCP tool registration, draft validation, FA(3) generation, KSeF gateway boundaries, and local stdio startup.

• Live KSeF TEST readiness, guarded TEST submit, invoice readback, and UPO readback with real TEST credentials.

• Docker/Streamable HTTP startup shape and OAuth resource-server validation code paths.

Still pending:

• Manual Claude Desktop stdio smoke from inside the Claude Desktop app.

• Live hosted HTTP/OAuth smoke against a real public URL and OAuth provider.

Use docs/MANUAL_SMOKE_RUNBOOK.md when completing those external gates.

Requirements

• Python 3.12 or 3.13.

• uv for local development and command execution.

• KSeF TEST token or certificate credentials.

• A Polish NIP for the configured tenant.

• Docker, only if you want the containerized HTTP deployment.

Local Setup

Clone the repository and install dependencies:

git clone https://github.com/olegtyshcneko/ksef-mcp.git
cd ksef-mcp
uv sync

Create local configuration:

cp .env.example .env
cp seller_profile.example.yaml seller_profile.yaml

Edit .env and replace the placeholder values. Start with:

KSEF_ENV=test
KSEF_AUTH_MODE=token
KSEF_NIP=REPLACE_WITH_YOUR_NIP
KSEF_TEST_NIP=REPLACE_WITH_TEST_NIP
KSEF_TOKEN=REPLACE_WITH_TEST_TOKEN
KSEF_ALLOW_PROD=false
MCP_TRANSPORT=stdio

Edit seller_profile.yaml with your seller and payment defaults. The real .env, seller_profile.yaml, and data/ directory are ignored by git.

Run the local checks:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-config-check
UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-local-preflight \
  --seed docs/examples/first_standard_invoice_seed.example.json
UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-stdio-smoke

The local preflight does not call KSeF and reports safety fields such as configured_ledger_may_be_touched_by_stdio=true.

Then prove KSeF TEST readiness:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-test-readiness-smoke

You can also validate the first invoice seed without touching your real ledger:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-first-draft-dry-run \
  --seed docs/examples/first_standard_invoice_seed.example.json

The dry run should report ready_for_prepare=true, real_ledger_touched=false, and no KSeF network use.

If KSEF_TEST_NIP intentionally equals KSEF_NIP, either set KSEF_ALLOW_REAL_NIP_IN_TEST=true or pass --use-real-nip-ack to the smoke commands.

Claude Desktop

Generate a redacted Claude Desktop config preview:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-claude-config-preview

The preview reports secrets_included=false. Paste the generated mcpServers block into claude_desktop_config.json, then restart Claude Desktop. Keep secrets in .env; do not paste KSeF tokens, certificate passwords, NIPs, or customer data into the desktop config.

See docs/CLAUDE_DESKTOP.md for the full first-use flow.

Manual Evidence Notes

For manual gates, create a private redaction-safe evidence template:

mkdir -p data
UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-manual-smoke-template --format markdown \
  > data/manual_smoke_evidence.md

Before sharing or committing filled notes, scan them:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-manual-smoke-evidence-check \
  --path data/manual_smoke_evidence.md

First Invoice Flow

1. Run ksef-mcp-test-readiness-smoke.

2. Start a draft with ksef_start_invoice_draft.

3. Patch missing fields with ksef_update_invoice_draft.

4. Confirm advisory/source-derived fields when required.

5. Run ksef_validate_invoice_draft until ready_for_prepare=true.

6. Call ksef_prepare_invoice to build FA(3) XML and create a confirmation token.

7. Optionally call ksef_render_invoice_pdf for a local preview.

8. Call ksef_submit_invoice only after reviewing the prepared XML/preview and confirming the write.

9. Download the UPO with ksef_download_upo.

Minimal start call:

{
  "seed": {
    "...": "contents of docs/examples/first_standard_invoice_seed.example.json"
  }
}

If the response includes missing_fields, patch the draft and validate again:

{
  "draft_id": "returned-draft-id",
  "patch": {
    "buyer": {
      "name": "Corrected buyer name"
    }
  }
}

Only call ksef_prepare_invoice after ksef_validate_invoice_draft returns ready_for_prepare=true, missing_fields=[], and blocking_errors=[].

For a terminal-only TEST submit smoke:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-test-submit-smoke \
  --seed docs/examples/first_standard_invoice_seed.example.json \
  --confirm-submit-to-ksef-test

Remote HTTP Deployment

Use remote mode when a service, hosted agent, ChatGPT app, Claude.ai, or another cloud MCP client must reach the server over HTTPS.

This server is an OAuth resource server. It validates bearer JWTs against your configured issuer, audience, JWKS URL, and required scope. It does not issue tokens, host login pages, implement PKCE, or dynamically register clients. Put those responsibilities in an external OAuth/OIDC provider or platform gateway.

Minimal environment:

MCP_TRANSPORT=http
MCP_PUBLIC_URL=https://ksef-mcp.example.com/mcp
OAUTH_ISSUER=https://issuer.example.com/
OAUTH_AUDIENCE=https://ksef-mcp.example.com/mcp
OAUTH_JWKS_URL=https://issuer.example.com/.well-known/jwks.json
OAUTH_REQUIRED_SCOPES=ksef.mcp
KSEF_ENV=test
KSEF_ALLOW_PROD=false

Run locally:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp

Or with Docker Compose:

cp .env.example .env
# Fill KSEF_*, MCP_PUBLIC_URL, and OAuth values.
docker compose up --build ksef-mcp

Before giving the URL to users or clients, run:

UV_CACHE_DIR=/tmp/uv-cache uv run ksef-mcp-remote-preflight

Expected success output includes oauth_network_used=false; this command does not fetch JWKS, call OAuth, start the hosted server, or touch KSeF. Then complete a live hosted OAuth smoke from the real client. See docs/REMOTE_DEPLOYMENT.md for provider notes and the smoke checklist.

Production Safety

Production sends require both:

KSEF_ENV=prod
KSEF_ALLOW_PROD=true

Keep KSEF_ALLOW_PROD=false until your TEST readiness, TEST submission, UPO download, client connection, and operational monitoring have all passed. ksef_submit_invoice is marked as a destructive MCP tool and also enforces confirmation-token and idempotency checks server-side.

Useful Commands

uv run ksef-mcp-config-check
uv run ksef-mcp-local-preflight --seed docs/examples/first_standard_invoice_seed.example.json
uv run ksef-mcp-stdio-smoke
uv run ksef-mcp-test-readiness-smoke
uv run ksef-mcp-first-draft-dry-run --seed docs/examples/first_standard_invoice_seed.example.json
uv run ksef-mcp-test-submit-smoke --seed docs/examples/first_standard_invoice_seed.example.json --confirm-submit-to-ksef-test
uv run ksef-mcp-remote-preflight
uv run pytest
uv run ruff check .
uv run mypy

More Documentation

• docs/CLAUDE_DESKTOP.md - local Claude Desktop setup.

• docs/REMOTE_DEPLOYMENT.md - Streamable HTTP and OAuth deployment.

• docs/MANUAL_SMOKE_RUNBOOK.md - manual validation evidence.

• docs/READINESS_AUDIT.md - current status and remaining gates.

• docs/LOCAL_KNOWLEDGE.md - local FTS/vector/LLM source extraction.

• docs/main_spec.md - implementation source spec.

• CHANGELOG.md - release history.