Skip to main content
Glama

mcp-eureka

An MCP (Model Context Protocol) server for the EUREKA system of the Ministerstwo Finansow / MF (Ministry of Finance) (eureka.mf.gov.pl) - 550,000+ documents of Polish tax practice, including 517,000+ individual interpretacje podatkowe (tax interpretations) of the Krajowa Informacja Skarbowa / KIS (National Revenue Information), general interpretations, tax explanations, and binding rate (WIS) and excise (WIA) information.

The largest single corpus of tax practice in Poland, available to Claude / Cursor / VS Code MCP agents with verifiable citations (signature + URL + date).

Status: v0.1.0 | License: MIT | Maintainer: MateMatic

Tax interpretations are not a source of law - they are the practice of authorities (art. 14a-14s of the Tax Ordinance). Legal protection applies to the applicant of a given individual interpretation.

Data source

The public JSON API of the EUREKA portal (Angular SPA backend, no key required), verified live on 2026-07-08:

  • POST /api/public/v1/wyszukiwarka/informacje/?size=N&page=N&sort=DT_WYD,desc - search (filters: SYG, KATEGORIA_INFORMACJI as an array of ids, DT_WYD_start/DT_WYD_end; searchQuery in the body). The trailing slash before ? is mandatory - without it the backend returns HTTP 500.

  • GET /api/public/v1/informacje/{id} - full document (metadata + HTML content).

  • GET /api/public/v1/pozycje-slownika/wyszukiwarka?kodSlownika=KATEGORIA_INFORMACJI - category dictionary (28 entries).

Related MCP server: mcp-nsa

MCP tools

  • search(query?, full_phrase?, signature?, category_ids?, date_from?, date_to?, page?, page_size?) - search with filters; sorted by issue date descending.

  • get_interpretation(id) - full document by ID_INFORMACJI (thesis + first 3000 characters of content).

  • search_by_signature(signature) - shortcut: by signature, full (0112-KDIL3.4012.367.2026.2.AK) or prefix (0112-KDIL3).

  • list_categories() - category dictionary (id -> name) for category_ids.

Every response includes structuredContent.citations (title, url, signature, issue_date) - the contract consumed by Patron and any MCP agent.

Quickstart

npm install
npm run build
npm start                # stdio transport

npm run drift            # consistency INSTRUCTIONS <-> TOOLS <-> ErrorCode
npm run test:parse       # offline - fixtures from real API responses
npm run smoke            # LIVE - eureka.mf.gov.pl (throttled 2 req/s)

MCP client configuration (mcp-servers.json):

{
  "mcpServers": {
    "eureka": {
      "command": "node",
      "args": ["<path>/mcp-eureka/dist/index.js"]
    }
  }
}

MateMatic Polish-law connectors

mcp-saos (common courts/SN/TK/KIO) · mcp-nsa (NSA + 16 WSA) · mcp-eureka (this one) · mcp-isap (Dz.U. + M.P.) · mcp-krs (KRS) · kio-orzeczenia-mcp (KIO)

Fleet convention: one connector = one source (single-source). Every call returns a citable source, zero content modification, stateless.

Disclaimer

The data comes from the public EUREKA system of the Ministry of Finance. The connector does not modify content, throttles requests (max 2 req/s), and identifies itself with a User-Agent carrying the repo address. Interpreting the law in a specific case requires your own individual interpretation or the opinion of a tax advisor.

License

MIT - see LICENSE.

Citation: MateMatic Solutions (2026), mcp-eureka - MCP server for Polish tax interpretations (EUREKA/KIS), https://github.com/matematicsolutions/mcp-eureka, MIT.

Available Tools

4 tools
get_interpretationA
Read-onlyIdempotent

Pobiera pelny dokument EUREKA po ID_INFORMACJI (z wynikow 'search'). Zwraca metadane (sygnatura, kategoria, daty), teze i pierwsze 3000 znakow pelnej tresci (HTML odarty do tekstu). Bledy: missing_arg (brak id), not_found (id poza baza), upstream_error.

Inputs: id (required).

list_categoriesA
Read-onlyIdempotent

Zwraca slownik kategorii dokumentow EUREKA (id -> nazwa, 28 pozycji): interpretacje indywidualne/ogolne, objasnienia podatkowe, WIS, WIA, orzeczenia sadow itd. Uzyj id w parametrze category_ids narzedzia search. Bledy: upstream_error.

Inputs: no named parameters.

search_by_signatureA
Read-onlyIdempotent

Skrot: szuka dokumentu po sygnaturze (pelnej lub prefiksie). Odpowiednik search z parametrem signature. Bledy: missing_arg (brak signature), upstream_error.

Inputs: signature (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    Tools are mostly distinct: search by query, search_by_signature is a convenient shortcut, get_interpretation for full document, list_categories for filter options. However, search_by_signature overlaps with search with a signature parameter, which could cause confusion about which to use.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: get_interpretation, list_categories, search, search_by_signature. The naming is clear and predictable.

    Tool Count5/5

    4 tools are appropriate for the server's purpose: searching and retrieving tax interpretation documents. The set is well-scoped without unnecessary bloat.

    Completeness4/5

    Covers core read-only operations: searching with filters, retrieving full content, and category listing. Missing pagination support for search results and full content retrieval beyond 3000 characters, but these are minor for typical use.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers