vzeman/ares-mcp-server

ARES MCP Server

A Model Context Protocol (MCP) server that provides access to the Czech ARES (Administrativní registr ekonomických subjektů) API - the official business registry of the Czech Republic.

Custom MCP Server Development

We develop custom MCP Servers for our customers. If you need your own MCP server for your system similar to this MCP server, please contact us (https://www.flowhunt.io/contact/). Read more how we develop MCP Servers for our customers: https://www.flowhunt.io/services/mcp-server-development/

Demo

See the ARES MCP Server in action within Claude Desktop:

The demo shows:

• 🔍 Searching for companies by name (e.g., "AiMingle")
• 📋 Getting detailed company information by IČO
• ✅ Validating IČO numbers
• 🏢 Searching in specific registries
• 📊 Using advanced filters (legal form, CZ-NACE codes, etc.)

Quick Start

1. Install the server:

   git clone https://github.com/yourusername/ares-mcp-server.git
   cd ares-mcp-server
   pip install -e .
   

2. Add to Claude Desktop config:

   {
     "mcpServers": {
       "ares": {
         "command": "python3",
         "args": ["-m", "ares_mcp_server.server"],
         "cwd": "/path/to/ares-mcp-server"
       }
     }
   }
   

3. Restart Claude Desktop and start searching Czech companies!

Features

• Full implementation of ARES API endpoints
• Complex search with multiple filters (IČO, name, address, legal form, CZ-NACE, etc.)
• Registry-specific searches (Public Registry, Trade Registry, Schools, etc.)
• Built-in rate limiting
• Optional authentication support
• Proper Czech naming following the API documentation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

Quick Install

# Clone the repository
git clone https://github.com/yourusername/ares-mcp-server.git
cd ares-mcp-server

# Run automated setup
./run.sh  # macOS/Linux
# or
run.bat   # Windows

Manual Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create configuration
cp .env.example .env

Configuration

Configure the server using environment variables in .env:

# Rate limiting (default: 100 requests per 60 seconds)
ARES_RATE_LIMIT_REQUESTS=100
ARES_RATE_LIMIT_WINDOW=60

# Optional authentication token
ARES_AUTH_TOKEN=your_token_here

# Logging level
LOG_LEVEL=INFO

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ares": {
      "command": "python3",
      "args": ["-m", "ares_mcp_server.server"],
      "cwd": "/path/to/ares-mcp-server"
    }
  }
}

Available Tools

1. vyhledat_ekonomicke_subjekty

Main search tool - Search economic entities using complex filters

Parameters:

• start (optional): Starting position (default: 0)
• pocet (optional): Number of results (default: 20, max: 200)
• razeni (optional): Sort order array ["ICO", "OBCHODNI_JMENO_DESC", etc.]
• ico (optional): Array of IČO numbers to search
• obchodniJmeno (optional): Business name
• sidlo (optional): Address filter object
  • kodCastiObce: District code
  • kodObce: Municipality code
  • textovaAdresa: Text address search
  • etc.
• pravniForma (optional): Array of legal form codes
• financniUrad (optional): Array of tax office codes
• czNace (optional): Array of CZ-NACE activity codes (max 5)

2. najit_ekonomicky_subjekt

Get detailed information about a specific economic entity

Parameters:

• ico (required): IČO number (8 digits)

3. vyhledat_v_registru

Search in a specific registry

Parameters:

• registry (required): Registry code
  • vr: Veřejné rejstříky (Public Registers)
  • res: Registr ekonomických subjektů (Economic Entities)
  • rzp: Registr živnostenského podnikání (Trade Licensing)
  • nrpzs: Národní registr poskytovatelů zdravotních služeb (Healthcare)
  • rpsh: Registr politických stran a hnutí (Political Parties)
  • rcns: Registr církví a náboženských společenství (Churches)
  • szr: Společný zemědělský registr (Agricultural)
  • rs: Registr škol (Schools)
  • ceu: Centrální evidence úpadců (Bankrupts)
• Plus same search parameters as main search

4. najit_v_registru

Get entity from specific registry by IČO

Parameters:

• registry (required): Registry code
• ico (required): IČO number

5. validovat_ico

Validate IČO format and check existence

Parameters:

• ico (required): IČO to validate

6. vyhledat_ciselniky

Search codebooks and nomenclatures

7. vyhledat_adresy

Search standardized addresses

8. vyhledat_notifikace

Search notification batches

Example Usage in Claude Desktop

Once configured, you can interact with ARES data directly in Claude Desktop. Here are some common use cases:

🔍 Basic Company Search

Ask Claude: "Search for companies with name containing 'Microsoft' in ARES"

Claude will use:

vyhledat_ekonomicke_subjekty with:
- obchodniJmeno: "Microsoft"
- pocet: 10

📊 Get Company Details

Ask Claude: "Get details for company with IČO 26168685"

Claude will use:

najit_ekonomicky_subjekt with:
- ico: "26168685"

✅ Validate IČO

Ask Claude: "Is IČO 26168685 valid?"

Claude will use:

validovat_ico with:
- ico: "26168685"

🏭 Industry-Specific Search

Ask Claude: "Find all restaurants in Prague"

Claude will use:

vyhledat_ekonomicke_subjekty with:
- czNace: ["56"]  # Restaurants and food service
- sidlo: { "nazevObce": "Praha" }
- pocet: 50

📋 Search Multiple Companies

Ask Claude: "Get info for companies with IČO 26168685 and 00000019"

Claude will use:

vyhledat_ekonomicke_subjekty with:
- ico: ["26168685", "00000019"]

🏢 Registry-Specific Search

Ask Claude: "Search for software companies in the trade registry"

Claude will use:

vyhledat_v_registru with:
- registry: "rzp"
- obchodniJmeno: "software"

Development

Project Structure

ares-mcp-server/
├── ares_mcp_server/
│   ├── __init__.py
│   ├── server.py           # Entry point
│   ├── server_v3.py        # Main server implementation
│   ├── api_client_v3.py    # ARES API v3 client
│   └── tools_v3.py         # Tool definitions
├── tests/
├── examples/
├── requirements.txt
├── pyproject.toml
└── README.md

Running Tests

source venv/bin/activate
pytest tests/

API Documentation

This server implements the official ARES API. For detailed API documentation, see:

• ARES Swagger UI
• ARES Website
• API Base URL: https://ares.gov.cz/ekonomicke-subjekty-v-be/rest

Changelog

v0.3.0 (2025-07-04)

• Complete rebuild based on ARES API v3 specification
• Tool names now match API endpoints (Czech names)
• Proper parameter structure matching API documentation
• Support for all search filters including address components
• Added registry-specific search endpoints
• Added utility endpoints (codebooks, addresses, notifications)

License

MIT License

Support

For issues or questions:

• Create an issue on GitHub
• Check the ARES API documentation

Acknowledgments

This server integrates with the Czech ARES API provided by the Ministry of Finance of the Czech Republic.