promua-mcp
Optional Brave Search API fallback provider for Prom.ua marketplace searches when direct Prom SSR parsing fails or when external search is explicitly requested.
Optional SearXNG fallback search provider for Prom.ua marketplace searches when direct Prom SSR parsing fails or when external search is explicitly requested.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@promua-mcp search Prom.ua for DT-25-10 наконечник under 80 UAH"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
promua-mcp
English | Українська
Browser-free MCP server for Prom.ua.
It combines:
Direct marketplace search against Prom.ua's public SSR search pages.
DuckDuckGo HTML fallback with no API key or account.
Optional seller tools through Prom.ua's official Public API v1.
Local saved searches for repeatable workflows.
There is no Playwright, Chromium, browser automation, browser profile, cookie/session storage, or GUI control.
Quick start
The published npm package needs no credentials for normal product search.
Run it directly:
npx -y promua-mcpOr configure an MCP client to spawn it:
{
"mcpServers": {
"promua": {
"command": "npx",
"args": ["-y", "promua-mcp"]
}
}
}A global install also works:
npm install -g promua-mcp
promua-mcpNo Prom.ua token or search API key is required for marketplace search.
Related MCP server: Web Explorer MCP
Marketplace search
prom_search_products first queries Prom.ua directly:
GET https://prom.ua/ua/search?search_term=<query>&page=<n>Prom embeds product cards as schema.org Product JSON-LD, so the MCP can extract structured data from the server-rendered HTML:
product id
title
canonical URL
price / currency
min/max price when a product contains multiple offers
seller / sellers
availability
image
SKU
brand
description
Prom's embedded total result count
No API token is required.
Search arguments
{
"query": "DT-25-10 наконечник",
"min_price": 20,
"max_price": 80,
"sort": "price_asc",
"limit": 20,
"offset": 0,
"max_pages": 5,
"source": "auto"
}source=auto— direct Prom SSR first, DuckDuckGo fallback if direct parsing fails.source=prom— require direct Prom SSR.source=duckduckgo— force the DuckDuckGo HTML fallback.offsetmaps to Prom pages when possible.min_price/max_priceuse Prom's JSON-LD prices for direct search.price_asc/price_descsort the scanned result window.source_total,scanned_pages,next_offset,exhaustiveandwarningmake coverage explicit.
DuckDuckGo fallback
The fallback uses DuckDuckGo's static no-JavaScript HTML search:
https://html.duckduckgo.com/html/No API key, account or token is required.
The fallback searches for site:prom.ua <query>, unwraps DuckDuckGo redirect URLs and returns only Prom.ua results.
It is intentionally treated as best-effort and non-exhaustive. DuckDuckGo may throttle automated requests or return a bot-detection challenge; the MCP detects that and fails clearly instead of trying to bypass it.
Do I need PROM_API_TOKEN?
For product search: No
If your use case is:
find products on Prom.ua;
compare prices;
filter by price;
paginate search results;
save and rerun searches;
leave PROM_API_TOKEN empty.
Marketplace search does not use the seller API.
For managing your own Prom.ua store: Yes
The token is useful only if you are a Prom.ua seller and want the MCP to work with your company's own cabinet data through the official Public API.
Seller tools can read or manage:
your products and groups;
your orders;
your clients;
your messages;
delivery options;
payment options;
order statuses.
Prom.ua describes its Public API as remote access to data in the company cabinet, not as a buyer/search API.
You can create a token in the seller cabinet:
Settings → API token managementProm lets you choose permissions per API group: no access, read-only, or read/write.
For read-only use, grant only the permissions you need.
Official seller documentation:
Seller writes are separately disabled
Even if a token has write permissions, this MCP blocks mutations unless you explicitly enable:
PROM_ALLOW_WRITES=trueSo a read-only setup can simply keep:
PROM_ALLOW_WRITES=falseSeller tools
Read
prom_seller_list_productsprom_seller_get_productprom_seller_get_product_by_external_idprom_seller_list_ordersprom_seller_get_orderprom_seller_list_clientsprom_seller_get_clientprom_seller_list_messagesprom_seller_get_messageprom_seller_list_groupsprom_seller_list_payment_optionsprom_seller_list_delivery_optionsprom_seller_list_order_status_options
Write
prom_seller_edit_productsprom_seller_edit_products_by_external_idprom_seller_set_order_statusprom_seller_set_message_statusprom_seller_reply_message
Saved searches
prom_saved_search_listprom_saved_search_createprom_saved_search_runprom_saved_search_delete
Saved searches are stored locally as JSON and replay the same structured search arguments.
Buyer account actions
Buyer-account actions such as Favorites, cart mutation, buyer order history and authenticated buyer messages are not implemented.
They are not exposed by the documented Prom seller Public API, and this project intentionally does not emulate them with a browser.
Configuration
Minimal search-only setup:
PROM_HTTP_TIMEOUT_MS=15000
PROM_DATA_DIR=
PROM_SAVED_SEARCHES_FILE=Optional seller mode:
PROM_API_TOKEN=
PROM_API_BASE_URL=https://my.prom.ua/api/v1
PROM_ALLOW_WRITES=falseDocker
docker build -t promua-mcp .
docker run --rm -i --env-file .env promua-mcpSafety / access model
ordinary HTTP requests only;
no browser automation;
no access-control bypass;
no buyer cookies/sessions;
no checkout or payment automation;
seller writes are opt-in;
direct Prom search fails closed if the expected JSON-LD structure disappears;
DuckDuckGo challenges are detected, not bypassed.
Branching and releases
Development happens on devel. The main branch is release-only.
Normal flow:
work on
devel(or a short-lived branch targetingdevel);keep CI green;
open a pull request from
develtomain;merge the PR;
the successful
mainmerge automatically creates a GitHub Release and publishes npm.
Direct pushes to main are rejected by the repository policy workflow after bootstrap. Server-side GitHub branch protection should also require PRs and the CI/Main Branch Policy checks.
Automatic versioning
Every successful merge into main releases a version.
If the repository version is already published, the workflow increments the patch version automatically.
To intentionally release a new minor or major line, raise the version in
develfirst (for example0.4.0or1.0.0). If it is higher than the current npm version, that explicit version wins.The release workflow creates a release-only commit under the version tag, so it does not need to push a version-bump commit back into protected
main.
The first automatic release uses the current repository version when the package is not yet published.
npm authentication
Create an npm Granular Access Token with package publish permissions and add it to this GitHub repository as an Actions secret named exactly:
NPMThe workflow uses it only as:
NODE_AUTH_TOKEN=${{ secrets.NPM }}Before publishing, it runs npm whoami and fails clearly if the secret is missing, expired or invalid.
Release validation
Before a release is published, GitHub Actions validates:
the
mainupdate came from a merged PR (except the one-time bootstrap release);the package name, existing npm metadata and repository URL match this project;
locked dependencies install with
npm ci;typecheck and unit tests pass;
the project builds;
the built MCP server completes a real stdio handshake and exposes its tools;
the npm tarball contains the expected files and no source/tests/workflows;
the version has not already been published.
The final publish command is:
npm publish --access public --provenanceThe same workflow creates the matching Git tag and GitHub Release.
Development## Development
npm ci
npm run check
npm test
npm run build
npm run test:runtime
npm run verify:packageAcknowledgment
The direct Prom SSR / JSON-LD approach was validated against the MIT-licensed cuzin85/marketua Prom provider, then reimplemented in TypeScript with broader Product/Offer parsing, multi-page scanning, explicit coverage metadata and a no-auth DuckDuckGo fallback.
License
MIT
Available Tools
24 toolsprom_saved_search_createC
Save a structured Prom.ua search definition locally for repeat execution.
Inputs: name (required), search (required).
prom_saved_search_deleteC
Delete a locally saved Prom.ua search.
Inputs: id (required).
prom_saved_search_listB
List locally saved Prom.ua searches.
Inputs: no named parameters.
prom_saved_search_runB
Run a locally saved Prom.ua search using direct Prom SSR with DuckDuckGo fallback.
Inputs: id (required).
prom_search_productsB
Search Prom.ua directly via its public SSR search page and Product JSON-LD. Falls back to DuckDuckGo HTML search if direct Prom parsing fails.
Inputs: query (required), sort, limit, offset, +4 more.
prom_search_urlA
Build a Prom.ua marketplace search URL for a query. Requires no API credentials and performs no automated page access.
Inputs: query (required).
prom_seller_edit_productsB
Edit seller products by Prom.ua ids. Disabled unless PROM_ALLOW_WRITES=true.
Inputs: payload (required).
prom_seller_edit_products_by_external_idB
Edit seller products by external ids. Disabled unless PROM_ALLOW_WRITES=true.
Inputs: payload (required).
prom_seller_get_clientC
Get one seller client by id.
Inputs: id (required).
prom_seller_get_messageC
Get one seller message by id.
Inputs: id (required).
prom_seller_get_orderC
Get one seller order by id.
Inputs: id (required).
prom_seller_get_productB
Get one seller product by Prom.ua product id.
Inputs: id (required).
prom_seller_get_product_by_external_idB
Get one seller product by external id.
Inputs: id (required).
prom_seller_list_clientsC
List clients of the authenticated Prom.ua seller company.
Inputs: limit, last_id.
prom_seller_list_delivery_optionsB
List seller delivery options.
Inputs: no named parameters.
prom_seller_list_groupsC
List seller product groups.
Inputs: limit, last_id.
prom_seller_list_messagesC
List messages for the authenticated Prom.ua seller company.
Inputs: limit, status, date_to, last_id, +1 more.
prom_seller_list_ordersC
List orders from the authenticated Prom.ua seller company.
Inputs: limit, status, date_to, last_id, +4 more.
prom_seller_list_order_status_optionsC
List seller order status options.
Inputs: no named parameters.
prom_seller_list_payment_optionsB
List seller payment options.
Inputs: no named parameters.
prom_seller_list_productsC
List products from the authenticated seller's Prom.ua company via Public API.
Inputs: limit, last_id, group_id, last_modified_to, +1 more.
prom_seller_reply_messageB
Reply to a seller message through Prom.ua. Disabled unless PROM_ALLOW_WRITES=true.
Inputs: id (required), message (required).
prom_seller_set_message_statusC
Change status for one or more seller messages. Disabled unless PROM_ALLOW_WRITES=true.
Inputs: ids (required), status (required).
prom_seller_set_order_statusB
Change status for one or more seller orders. Disabled unless PROM_ALLOW_WRITES=true.
Inputs: ids (required), status (required), cancellation_text, cancellation_reason.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Most tools target distinct resource+action pairs, and the by-id vs by-external-id pairs are clarified in their descriptions. Minor overlap remains between prom_search_products and prom_saved_search_run (both execute searches with the same fallback), which could cause slight misselection.
Strong, predictable prom_<domain>_<verb>_<noun> snake_case pattern across the set. A few tools (prom_search_url, prom_search_products) use 'search' as a verb while seller tools use list/get/edit/set, causing minor inconsistency but still readable.
24 tools is on the heavy side and includes granular duplication such as separate by-id and by-external-id get/edit variants plus multiple option-list tools. The breadth is partly justified by the seller/public-search split, but the surface feels padded.
Read coverage is strong, but write/lifecycle operations are uneven: products support edit but not create or delete, clients and groups are list/get-only, and messages lack deletion. These notable gaps will force agents to work around missing CRUD operations.
Maintenance
Related MCP Connectors
Product search for AI shopping agents: prices and buy links from big retailers. No key needed.
SEO and market data: SERP, keyword volume, backlinks, site audit, Maps, reviews, traffic, ChatGPT visibility, Amazon, jobs, DNS, bulk HTTP/API requests.
Track prices & price history on any online shop, with alerts and an API
Search and look up products across thousands of online stores, normalized into one schema.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables privacy-focused web searches through the Presearch API and web content scraping. Supports multi-language search, configurable safe search, result caching, and multiple export formats (JSON, CSV, Markdown).4-
- AlicenseAqualityDmaintenanceEnables private web search and webpage content extraction using a local SearxNG instance, prioritizing user privacy and autonomy.212 PyPI2MIT
- FlicenseAqualityCmaintenanceEnables private, free web searches through a self-hosted SearXNG instance, replacing default search tools without API keys, rate limits, or third-party tracking.1-
- AlicenseAqualityCmaintenanceEnables privacy-focused meta searches across multiple search engines through SearXNG, with category, language, time-range, and safe-search controls, plus fallback instances. It correctly treats reachable instances with zero results as empty results rather than outages.11MIT