ares-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ares-mcp Check IČO 04084063 — who is it, are they VAT registered, and what do they do?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ares-mcp
An MCP server that gives an LLM agent grounded access to ARES, the Czech public business register: look a company up by its registration number (IČO), search the register by name, check VAT registration, and validate an IČO offline.
Why it exists. Ask a model about a Czech company and it will happily invent an address and a VAT number. That is fine in a chat and unacceptable in a back-office workflow — onboarding a client, checking a counterparty, filling a contract header. This server replaces the guess with a citable record from the state register: every answer carries a
source_urla human can open.
Tools
Tool | What it does | Network |
| Full company profile: name, seat, legal form, incorporation date, VAT ID, CZ-NACE activities, registers | ARES |
| Full-text search by business name, capped at 50 hits | ARES |
| Whether the subject is an active VAT payer, plus its VAT ID | ARES |
| Modulo-11 checksum validation and normalisation | none — pure logic |
Every tool returns a flat, documented JSON object. Failures come back as
{"error": "...", "message": "..."} instead of an exception, so the agent can
recover rather than abort the turn.
Related MCP server: ares-mcp
Quick start
git clone https://github.com/Tomi5037/ares-mcp.git
cd ares-mcp
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytestRun the server directly — it speaks MCP over stdio, so it waits for a client:
ares-mcp # stdio (default)
ares-mcp --transport streamable-http # run it as an HTTP service insteadBuilt on the official MCP Python SDK 2.x.
All four tools are annotated read_only_hint, so a client can auto-approve them
without prompting on every call.
Use it from Claude Code
claude mcp add ares -- /absolute/path/to/.venv/bin/ares-mcpUse it from Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"ares": {
"command": "/absolute/path/to/.venv/bin/ares-mcp"
}
}
}Then ask, in plain language:
"Check IČO 04084063 — who is it, are they VAT registered, and what do they do?"
{
"ico": "04084063",
"name": "CETIN a.s.",
"legal_form": "Joint-stock company (a.s.)",
"address": { "city": "Praha", "region": "Hlavní město Praha", "postal_code": "19000" },
"established_on": "2015-06-01",
"vat_number": "CZ04084063",
"vat_registered": true,
"is_active": true,
"activities": [{ "code": "6110", "section": "J", "section_label": "Information and communication" }],
"source_url": "https://ares.gov.cz/ekonomicke-subjekty?ico=04084063"
}How it works
LLM client (Claude Code / Desktop)
│ MCP over stdio
▼
server.py 4 tools, input validation, error contract
▼
client.py httpx async, timeouts, retry + backoff, TTL cache
▼
models.py raw ARES JSON -> flat pydantic schema
▼
ARES REST API v3 (public, no API key)Three decisions worth calling out:
Validate before you call. An IČO is checked locally with its modulo-11 checksum. A hallucinated or mistyped number never becomes an HTTP request, and the agent gets a specific error instead of a generic 404.
Normalise the payload. ARES answers with deeply nested Czech keys and the same record repeated once per source register.
models.pyflattens that into one documented schema — fewer tokens for the model, and one place to change when the upstream API moves.Cache and retry. A TTL cache keeps a repeated lookup off the state API, and transient 5xx/timeout responses are retried with exponential backoff. A public service you do not own is a dependency you should be polite to.
Configuration
All optional — ARES is a public API and needs no key.
Variable | Default | Meaning |
|
| API root |
|
| Per-request timeout |
|
| Attempts before giving up |
|
| Cache lifetime |
Tests
pytest --cov=ares_mcp # 45 tests, no network access
ruff check . && mypy src # lint and strict typingHTTP is mocked with httpx.MockTransport against payloads recorded from the
live API, so the suite is deterministic and runs offline in CI. Covered:
checksum edge cases, cache hits, retry on 503 and on timeout, 404 mapping,
missing upstream fields, and the exact JSON contract of every tool.
Limitations
ARES exposes public register data only; personal data of natural persons is returned by the upstream API in a limited form and this server does not enrich or store it.
The insolvency register (ISIR) is reported only as a presence flag, not with case detail.
Data is as fresh as ARES itself (
data_updated_onis passed through).
Roadmap
Streamable HTTP transport in addition to stdio
check_insolvencybacked by ISIRBulk lookup for a list of IČO with concurrency limits
Optional Redis cache for multi-process deployments
License
MIT — see LICENSE.
Data comes from ARES, operated by the Czech Ministry of Finance. This project is not affiliated with the Ministry.
Available Tools
4 toolscheck_vat_registrationARead-onlyIdempotent
Check whether a company is an active VAT payer and return its VAT ID.
Args: ico: The company's IČO.
Returns:
A vat_registered flag, the VAT ID and a link to the ARES record.
Inputs: ico (required). Returns: object
lookup_companyARead-onlyIdempotent
Look up a Czech company profile by its registration number (IČO).
Args: ico: The company's IČO; spaces and missing leading zeros are fine.
Returns: Name, registered seat, legal form, incorporation date, VAT ID, CZ-NACE activities and the registers the subject is listed in.
Inputs: ico (required). Returns: object
search_companiesARead-onlyIdempotent
Find Czech companies by a full or partial business name.
Args: name: The name to search for, e.g. "Renomia". limit: How many results to return (1-50).
Returns: The total number of matches and a list of hits with IČO, name and address.
Inputs: name (required), limit. Returns: object
validate_ico_numberARead-only
Validate an IČO offline via its modulo-11 checksum, without calling ARES.
Useful for a quick sanity check on form input or on a number read out of a scanned document, where 0/8 and 1/7 are routinely confused.
Args: ico: A string that is supposed to be an IČO.
Returns:
valid plus the normalised eight-digit form when the number is valid.
Inputs: ico (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The tools are mostly distinct: validate_ico_number handles offline checksum validation, search_companies finds by name, and lookup_company returns a full profile. There is minor overlap between lookup_company and check_vat_registration since both accept an IČO and lookup_company already returns a VAT ID, but the descriptions make the focused VAT-status purpose clear.
All tool names follow the same imperative verb_object pattern in snake_case: validate_, lookup_, search_, check_. This makes the tool set highly predictable and easy for an agent to reason about.
Four tools is a well-scoped size for an ARES-focused MCP server. Each tool covers a distinct, useful operation without redundancy or unnecessary bloat.
The domain is Czech company registry lookups, and the set covers offline validation, name search, full company profile retrieval, and VAT registration status. There are no important dead ends for common workflows involving finding and validating Czech companies.
Maintenance
Related MCP Connectors
Czech ARES company registry: VAT, insolvency, RÚIAN addresses, IČO/DIČ checks. All free, no auth.
Czech business register (ARES) — look up any Czech company or sole trader by IČO or by name, and…
Czech company and VAT checks, EU VAT validation, IBAN checksums and Czech National Bank rates.
Czech & Slovak business registry — company lookup by IČO, name, legal form, VAT. Official ARES.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides access to the Czech ARES business registry API, enabling search and retrieval of official information about Czech companies, validation of IČO numbers, and filtering by various criteria like legal form, industry codes, and location.2MIT
- AlicenseAqualityDmaintenanceMCP server for the Czech business registry ARES, enabling company validation, lookup, and due diligence checks directly from AI clients.1452 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to look up Czech companies, VAT status, entity KYC snapshots, address standardization, and Czech identifier validation via official ARES data.-
- AlicenseNot gradedqualityCmaintenanceEnables users to look up Czech companies and sole traders by IČO or by name, retrieving official registration data such as legal form, seat address, VAT number, and activity codes from the Ministry of Finance's ARES register.102 npmMIT