# Register UZ MCP Server
Model Context Protocol (MCP) server for Slovak Registry of Financial Statements (Register účtovných závierok) from Slovak Ministry of Finance based on the [API documentation](https://www.registeruz.sk/cruz-public/home/api).
**Author:** [@alhafoudh](https://github.com/alhafoudh)
## Features
- **Complete API Coverage**: All endpoints from the RegisterUZ Open API
- **Pydantic Models**: Fully typed response models for all API entities
- **25 MCP Tools**: Search, list, retrieve, and analyze financial data with labeled tables
- **8 MCP Resources**: Static classifier data and dynamic entity lookups
- **20 MCP Prompts**: Pre-built workflows for common integration scenarios
- **CLI Client**: Command-line tool for testing and exploration
## Data Available
- **Accounting Units** (Účtovné jednotky): Company/organization details including IČO, DIČ, address, legal form
- **Accounting Closures** (Účtovné závierky): Financial statement metadata and periods
- **Financial Reports** (Účtovné výkazy): Balance sheets, income statements with full data tables
- **Annual Reports** (Výročné správy): Annual report metadata and attachments
- **Templates** (Šablóny): Report structure definitions
- **Classifiers**: Legal forms, SK NACE codes, regions, districts, settlements
## Quick Start (Hosted Version)
Add the hosted MCP server to your Claude integration:
### Claude Code Integration (Hosted)
```bash
claude mcp add registeruz --transport http https://registeruz.fastmcp.app/mcp
```
### Claude Desktop Integration (Hosted)
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"registeruz": {
"type": "streamable-http",
"url": "https://registeruz.fastmcp.app/mcp"
}
}
}
```
### Make.com Integration (Hosted)
You can use the Autoform MCP server in [Make.com](https://www.make.com/) (formerly Integromat) using the **MCP Client - Call a tool** app:
1. Add the **MCP Client - Call a tool** module to your scenario
2. Create a new MCP server connection with these settings:
- **URL**: `https://registeruz.fastmcp.app/mcp`
- **API key / Access token**: Leave empty (no authentication required)
3. Select the tool you want to call and configure your query parameters
---
## Self-Hosted Installation
### From PyPI (recommended)
```bash
pip install registeruz-mcp
```
Or using uvx to run directly without installation:
```bash
uvx registeruz-mcp
```
### From source
```bash
# Clone the repository
git clone https://github.com/alhafoudh/registeruz-mcp.git
cd registeruz-mcp
# Install dependencies
uv sync
```
## Usage
### Run the MCP server (STDIO transport)
```bash
# If installed from PyPI
registeruz-mcp
# Or using uvx
uvx registeruz-mcp
# Or from source
uv run python registeruz_mcp.py
```
### Run with FastMCP CLI
```bash
uv run fastmcp run registeruz_mcp.py
```
### Inspect available tools
```bash
uv run fastmcp inspect registeruz_mcp.py
```
### Development mode with MCP Inspector
```bash
uv run fastmcp dev registeruz_mcp.py
```
## Available Tools
### List Tools (Get IDs)
| Tool | Description |
|------|-------------|
| `get_uctovne_jednotky` | Get accounting unit IDs changed since a date (supports filtering by IČO, DIČ, legal form) |
| `get_uctovne_zavierky` | Get accounting closure IDs changed since a date |
| `get_uctovne_vykazy` | Get financial report IDs changed since a date |
| `get_vyrocne_spravy` | Get annual report IDs changed since a date |
### Count Tools (Pagination)
| Tool | Description |
|------|-------------|
| `get_zostavajuce_id_uctovne_jednotky` | Count remaining accounting unit IDs |
| `get_zostavajuce_id_uctovne_zavierky` | Count remaining accounting closure IDs |
| `get_zostavajuce_id_uctovne_vykazy` | Count remaining financial report IDs |
| `get_zostavajuce_id_vyrocne_spravy` | Count remaining annual report IDs |
### Detail Tools
| Tool | Description |
|------|-------------|
| `get_uctovna_jednotka` | Get accounting unit details by ID |
| `get_uctovna_zavierka` | Get accounting closure details by ID |
| `get_uctovny_vykaz` | Get financial report with tables and data |
| `get_vyrocna_sprava` | Get annual report details by ID |
### Template Tools
| Tool | Description |
|------|-------------|
| `get_sablona` | Get template structure by ID |
| `get_sablony` | Get all available templates |
### Classifier Tools
| Tool | Description |
|------|-------------|
| `get_pravne_formy` | Get all legal forms |
| `get_sk_nace` | Get SK NACE classification codes |
| `get_druhy_vlastnictva` | Get ownership types |
| `get_velkosti_organizacie` | Get organization sizes |
| `get_kraje` | Get Slovak regions |
| `get_okresy` | Get Slovak districts |
| `get_sidla` | Get Slovak settlements |
### Download Tools
| Tool | Description |
|------|-------------|
| `get_attachment_url` | Get download URL for attachment |
| `get_financial_report_pdf_url` | Get PDF download URL for financial report |
### Labeled Data Tools
| Tool | Description |
|------|-------------|
| `get_uctovny_vykaz_with_labeled_tables` | Get financial report with labeled tables (combines report with template labels in one call) |
| `get_uctovny_vykaz_table_value_by_labels` | Search for specific values by row label, row code, column label, or table name |
## Available Resources
### Static Resources (Classifiers)
| URI | Description |
|-----|-------------|
| `ruz://classifiers/pravne-formy` | Legal forms |
| `ruz://classifiers/sk-nace` | SK NACE codes |
| `ruz://classifiers/druhy-vlastnictva` | Ownership types |
| `ruz://classifiers/velkosti-organizacie` | Organization sizes |
| `ruz://classifiers/kraje` | Regions |
| `ruz://classifiers/okresy` | Districts |
| `ruz://classifiers/sidla` | Settlements |
| `ruz://templates` | All templates |
### Dynamic Resource Templates
| URI Pattern | Description |
|-------------|-------------|
| `ruz://uctovna-jednotka/{id}` | Accounting unit by ID |
| `ruz://uctovna-zavierka/{id}` | Accounting closure by ID |
| `ruz://uctovny-vykaz/{id}` | Financial report by ID |
| `ruz://vyrocna-sprava/{id}` | Annual report by ID |
| `ruz://sablona/{id}` | Template by ID |
## Available Prompts
### Company Search Prompts
| Prompt | Description |
|--------|-------------|
| `search_company_by_ico` | Search for company by IČO and get financial statements |
| `search_company_by_dic` | Search for company by tax ID (DIČ) |
| `search_companies_by_legal_form` | Search for companies by legal form (e.g., s.r.o., a.s.) |
### Financial Analysis Prompts
| Prompt | Description |
|--------|-------------|
| `get_latest_financials` | Get latest financial statements for a company |
| `compare_financials_year_over_year` | Compare company financials across multiple years |
| `extract_financial_metrics` | Extract specific financial metrics (profit, assets, liabilities) |
| `get_balance_sheet` | Get balance sheet (Súvaha) data for a company |
| `get_income_statement` | Get income statement (Výkaz ziskov a strát) for a company |
### Change Tracking & Monitoring Prompts
| Prompt | Description |
|--------|-------------|
| `analyze_changes` | Analyze changes in accounting units over a period |
| `monitor_new_filings` | Monitor new financial statements filed since a date |
| `track_company_changes` | Track a specific company for recent changes |
### Document & Download Prompts
| Prompt | Description |
|--------|-------------|
| `get_company_documents` | Get all downloadable documents for a company |
| `get_annual_reports` | Download annual reports (Výročné správy) for a company |
### Template & Structure Prompts
| Prompt | Description |
|--------|-------------|
| `explore_template` | Explore financial report template structure |
| `list_all_templates` | List all available report templates with their purposes |
### Classifier & Reference Data Prompts
| Prompt | Description |
|--------|-------------|
| `get_location_hierarchy` | Get all Slovak regions and districts hierarchy |
| `get_legal_forms_explained` | Get all legal forms with explanations |
| `explore_sk_nace` | Explore SK NACE industry classification codes |
### Bulk/Export Prompts
| Prompt | Description |
|--------|-------------|
| `bulk_export_companies` | Export basic data for multiple companies |
| `generate_financial_summary` | Generate comprehensive company financial summary report |
## Claude Code Integration (Self-Hosted)
### Using uvx (recommended)
Run the server directly from PyPI without installation:
```bash
claude mcp add registeruz -- uvx registeruz-mcp
```
### Using local installation
If you've cloned the repository:
```bash
claude mcp add registeruz -- uv run --directory /path/to/registeruz-mcp python registeruz_mcp.py
```
## Claude Desktop Integration (Self-Hosted)
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
### Using uvx (recommended)
```json
{
"mcpServers": {
"registeruz": {
"command": "uvx",
"args": ["registeruz-mcp"]
}
}
}
```
### Using local installation
```json
{
"mcpServers": {
"registeruz": {
"command": "uv",
"args": ["run", "--directory", "/path/to/registeruz-mcp", "python", "registeruz_mcp.py"]
}
}
}
```
## Development
### Install dev dependencies
```bash
uv sync --all-extras
```
### Run tests
```bash
uv run pytest -v
```
## License
MIT
