Horoshop Server

An unofficial MCP server for stores built on Horoshop.

This project connects AI agents, internal assistants, and MCP-compatible clients to the Horoshop API through a practical Model Context Protocol server. It is designed for teams that run e-commerce operations on Horoshop and want language models to interact with store data in a controlled, tool-based way.

This project is not affiliated with, endorsed by, or maintained by Horoshop. It is a community-built integration for the Horoshop ecosystem.

Why This Exists

Horoshop gives merchants a hosted e-commerce platform at horoshop.ua, but AI tools still need a reliable way to access store operations such as orders, catalog data, and order status updates. MCP is a good fit for that layer because it lets LLMs call clearly defined tools instead of improvising against raw APIs.

This server turns the Horoshop API into MCP tools that can be used from clients like Claude Desktop, Cursor, and other agent frameworks that support MCP over stdio.

Real Use Cases

This server is useful when you want AI to do real operational work around a Horoshop store, for example:

• customer support assistants that look up an order, confirm its current status, and hand back structured answers to an operator
• back-office agents that review new orders and move them into the next processing state
• catalog helpers that inspect product data before content updates or merchandising tasks
• internal dashboards where AI can answer questions like "show me the latest orders from today" or "find the product by ID and summarize its current state"
• automation flows that need a safe bridge between natural-language prompts and Horoshop API methods
• store operations copilots that combine Horoshop data with CRM, ERP, shipping, or analytics tooling

What The Server Does

The current implementation provides a compact but useful starting point:

• authenticates against the Horoshop API using either a token or login/password credentials
• exposes MCP tools for listing and fetching orders
• exposes MCP tools for listing and fetching products
• supports updating order status from an MCP client
• includes a generic passthrough tool for calling arbitrary Horoshop API functions

This gives you enough to start with real workflows while keeping the codebase small enough to extend quickly.

Example Agent Workflows

With this MCP server, an agent can support workflows such as:

• "Find order 12345 and tell me whether it has already moved to the shipped status."
• "List the newest orders and summarize which ones need manual attention."
• "Fetch product 9876 and prepare a short product brief for a support manager."
• "Update order 12345 to status 7 after warehouse confirmation."
• "Call a custom Horoshop API function that is not wrapped yet, then return the raw payload for inspection."

Environment

Copy .env.example to .env and configure:

• HOROSHOP_BASE_URL: your Horoshop store domain, for example https://your-store.example.com
• HOROSHOP_LOGIN: API login created in the Horoshop admin panel
• HOROSHOP_PASSWORD: API password created in the Horoshop admin panel
• HOROSHOP_TOKEN: optional token if you already use token-based access

You need either:

• HOROSHOP_TOKEN

or:

• HOROSHOP_LOGIN
• HOROSHOP_PASSWORD

Install

npm install

Run

npm run build
npm start

For development:

npm run dev

MCP Configuration Example

{
  "mcpServers": {
    "horoshop": {
      "command": "node",
      "args": [
        "D:/usr/www/mcp-dev/horoshop/dist/index.js"
      ],
      "env": {
        "HOROSHOP_BASE_URL": "https://your-store.example.com",
        "HOROSHOP_LOGIN": "api-login",
        "HOROSHOP_PASSWORD": "api-password"
      }
    }
  }
}

Available Tools

• horoshop_auth: verify authentication and confirm token access
• horoshop_list_orders: list orders using Horoshop order export functions
• horoshop_get_order: fetch one order by ID
• horoshop_list_products: list products using Horoshop catalog export functions
• horoshop_get_product: fetch one product by ID
• horoshop_update_order_status: change the status of an order
• horoshop_call_api: call any Horoshop API function with arbitrary JSON parameters

Who This Is For

This project is a strong fit for:

• Horoshop merchants who want AI assistants to work with store operations
• agencies building AI-enabled tooling for Horoshop clients
• developers integrating Horoshop into MCP-based automation stacks
• teams that want a base server they can customize for their own business rules

Current Scope

This repository focuses on the operational core first: authentication, orders, products, status updates, and a raw API escape hatch.

That means it is intentionally useful on day one, but not yet a complete wrapper for the full Horoshop API surface. The generic horoshop_call_api tool is included specifically so you can validate store-specific behavior and extend the server safely as new requirements appear.

Notes

The server assumes the Horoshop API endpoint pattern:

https://<domain>/api/<function>/

If your store exposes different function names or request shapes than the defaults currently wrapped in this repository, use horoshop_call_api first and then extend src/index.ts.

Source

Horoshop website: https://horoshop.ua/