matejsarlija/e-oglasna-mcp

e-Oglasna MCP Server

A Model Context Protocol (MCP) server that provides access to the Croatian e-Oglasna legal notices API. This server allows AI agents to search and retrieve legal notices, bankruptcy proceedings, and court documents from the official Croatian judicial system.

(in Croatian) e-Oglasna MCP Server

Poslužitelj Model Context Protocola (MCP) koji omogućuje pristup API-ju za e-Oglasnu ploču pravosuđa Republike Hrvatske. Ovaj poslužitelj omogućuje AI agentima (npr. Claude Code) pretraživanje i dohvat pravnih oglasa, stečajnih postupaka i sudskih dokumenata iz službenog pravosudnog sustava Republike Hrvatske.

Features

• Complete API Coverage: All e-Oglasna API endpoints implemented
• Rate Limiting: Built-in rate limiting (1000/hour, 5 per 5 seconds)
• Error Handling: Comprehensive error handling with proper MCP error codes
• Search Tools: Search all notices, court notices, bankruptcies, institution notices
• Detail Retrieval: Get specific notice details by UUID
• Court Information: Retrieve list of all courts in the system
• Export Access: Access to archived notice files

Installation

1. Clone or create the project:

mkdir e-oglasna-mcp-server
cd e-oglasna-mcp-server

2. Save the files:

   • Save the main server code as index.js
   • Save the package.json
   • Save this README as README.md

3. Install dependencies:

npm install

4. Make executable (if needed):

chmod +x index.js

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "e-oglasna": {
      "command": "node",
      "args": ["/path/to/your/e-oglasna-mcp/index.js"]
    }
  }
}

Standalone Testing

npm start

Available Tools

1. search_all_notices

Search all notices across the system.

Parameters:

• text (string): Search text (case number, title, subject, OIB)
• dateFrom (date): Published date from (YYYY-MM-DD)
• dateTo (date): Published date to (YYYY-MM-DD)
• noticeSourceType (array): Filter by source ["COURT", "INSTITUTION", "NOTARY_PUBLIC"]
• page (integer): Page number (default: 0)
• sort (array): Sort criteria ["datePublished", "expirationDate"]

2. get_notice_details

Get detailed information about a specific notice.

Parameters:

• uuid (string, required): Notice UUID

3. search_court_notices

Search notices from courts.

Parameters:

• text (string): Search text
• dateFrom (date): Published date from
• dateTo (date): Published date to
• courtCode (array): Court codes to filter by
• caseType (array): Case types ["NATURAL_PERSON_BANKRUPTCY", "LEGAL_PERSON_BANKRUPTCY", "OTHER"]
• debtorOib (array): Debtor OIB numbers
• page (integer): Page number

4. search_bankruptcies

Search legal person bankruptcy proceedings.

Parameters:

• text (string): Company name, OIB, or search text
• dateFrom (date): Published date from
• dateTo (date): Published date to
• courtCode (array): Court codes
• debtorOib (array): Company OIB numbers
• page (integer): Page number

5. search_consumer_bankruptcies

Search natural person (consumer) bankruptcy proceedings.

Parameters:

• text (string): Person name, OIB, or search text
• dateFrom (date): Published date from
• dateTo (date): Published date to
• courtCode (array): Court codes
• debtorOib (array): Person OIB numbers
• page (integer): Page number

6. search_institution_notices

Search notices from institutions (like FINA).

Parameters:

• text (string): Search text
• dateFrom (date): Published date from
• dateTo (date): Published date to
• institutionNoticeType (array): Notice types ["CALL_FOR_ADDRESS_SUBMISSION", "OTHER"]
• page (integer): Page number

7. get_all_courts

Get list of all courts in the system.

Parameters: None

8. get_export_files

Get list of available export/archive files.

Parameters: None

Example Usage

Once configured with Claude Desktop, you can ask:

• "Search for recent bankruptcy proceedings in Zagreb"
• "Find all court notices published this week"
• "Get details for notice UUID abc-123-def"
• "Show me all available courts"
• "Search for notices mentioning company OIB 12345678901"

Rate Limiting

The server implements the same rate limiting as the official API:

• Maximum 1000 requests per hour
• Maximum 5 requests per 5-second window

If limits are exceeded, the server will return appropriate error messages.

Error Handling

The server handles all common API errors:

• 429: Rate limit exceeded
• 404: Resource not found
• 400: Invalid request parameters
• 500: System errors

Development

Running in Development Mode

npm run dev

Project Structure

e-oglasna-mcp/
├── index.js          # Main MCP server implementation
├── package.json      # Node.js dependencies and scripts
└── README.md         # This file

API Documentation

This MCP server is based on the official e-Oglasna API documentation. For detailed information about response formats and data structures, refer to the original API documentation at https://e-oglasna.pravosudje.hr/dokumenti/api.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues related to this MCP server, please create an issue in the GitHub repository.

For questions about the underlying e-Oglasna API, refer to the official Croatian judicial system documentation.