cijene-mcp by senko - MCP Server

Cijene MCP

This is a Model Context Protocol (MCP) server for Cijene API, exposing the https://api.cijene.dev functionality to AI agents.

Cijene.dev is a comprehensive database of retail store prices in Croatia, allowing you to search for products, compare prices across different chains, and find stores by location.

Features

This MCP server provides the following tools for AI agents:

list_chains - List all available retail chains in Croatia
list_chain_stores - List all stores for a specific retail chain
search_stores - Search for stores by location and filters
get_products_by_ean - Get product information by EAN barcode
search_products - Search for products by keyword
get_stats - Get statistics for all retail chains

Installation

This project uses uv for dependency management.

Clone the repository:

git clone https://github.com/your-username/cijene-mcp.git
cd cijene-mcp

Install dependencies:

uv sync

Configure your API key:

cp .env.example .env
# Edit .env and add your Cijene.dev API key

Get your API key from cijene.dev.

Usage

The MCP server supports two transport modes:

stdio - For local use with Claude Desktop (default)
http - For remote access via HTTP

In both, the operation is stateless, for better compatibility with OpenAI MCP client implementation.

Running with stdio transport (Claude Desktop)

By default, the server runs with stdio transport for use with Claude Desktop:

uv run python -m cijene_mcp.server

Or explicitly set the transport:

MCP_TRANSPORT=stdio uv run python -m cijene_mcp.server

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "cijene": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cijene-mcp",
        "run",
        "python",
        "-m",
        "cijene_mcp.server"
      ]
    }
  }
}

Replace /path/to/cijene-mcp with the actual path to your cloned repository.

Running with HTTP transport (Remote Access)

To run the server as an HTTP endpoint for remote access:

MCP_TRANSPORT=http uv run python -m cijene_mcp.server

Or configure it in your .env file:

MCP_TRANSPORT=http
MCP_HTTP_PORT=8001  # Optional, defaults to 8001

The server will start on http://localhost:8001 (or your configured port) using Streaming HTTP for communication.

Available Tools

list_chains()

List all available retail chains in Croatia.

Returns: Dictionary containing list of retail chain codes

list_chain_stores(chain_code: str)

List all stores for a specific retail chain.

Parameters:

chain_code (str): The code identifying the retail chain (e.g., "konzum", "spar")

Returns: Dictionary containing list of stores for the specified chain

search_stores(chains?, city?, address?, lat?, lon?, d?)

Search for stores by location and filters.

Parameters:

chains (str, optional): Comma-separated chain codes to filter by
city (str, optional): City name to search in
address (str, optional): Address to search for
lat (float, optional): Latitude for geolocation search
lon (float, optional): Longitude for geolocation search
d (float, optional): Search distance in kilometers (default 10km)

Returns: Dictionary containing list of matching stores

get_products_by_ean(ean: str, date?, chains?)

Get product information by EAN barcode.

Parameters:

ean (str): The product EAN barcode (13 digits)
date (str, optional): Date in YYYY-MM-DD format for historical prices
chains (str, optional): Comma-separated chain codes to filter by

Returns: Dictionary containing product details and pricing information

search_products(q: str, date?, chains?)

Search for products by keyword.

Parameters:

q (str): Search query (product name or keyword)
date (str, optional): Date in YYYY-MM-DD format for historical prices
chains (str, optional): Comma-separated chain codes to filter by

Returns: Dictionary containing list of matching products. Each product includes:

ean: Product EAN barcode
brand: Product brand name
name: Product name
quantity: Product quantity
unit: Unit of measurement
chain_matches: Integer count of matching chain products found (e.g., 5 means this product was found in 5 different chain stores)

To get full pricing details for a specific product, use get_products_by_ean with the product's EAN code.

get_stats()

Get statistics for all retail chains.

Returns: Dictionary containing statistics per chain (price date, price count, store count)

Development

Running Tests

Run the test suite with coverage:

uv run pytest --cov=cijene_mcp --cov-report=term-missing

Run tests without coverage:

uv run pytest

Project Structure

cijene-mcp/
├── src/
│   └── cijene_mcp/
│       ├── __init__.py
│       ├── config.py      # Configuration management
│       ├── client.py      # Cijene API client wrapper
│       └── server.py      # FastMCP server with tools
├── tests/
│   ├── __init__.py
│   ├── conftest.py        # Pytest fixtures
│   ├── test_client.py     # Client tests
│   └── test_server.py     # Server tests
├── .env.example           # Environment variables template
├── pyproject.toml         # Project configuration
└── README.md

License

This code may be used, modified and distributed under the terms of the .