io.github.matematicsolutions/mcp-eureka

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).

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.