Skip to main content
Glama
OSMOS Marketing API MCP Server

OSMOS Marketing API MCP Server

OSMOS Marketing API MCP Server

Model Context Protocol server that exposes the OSMOS Marketing API registry as callable tools, so an AI agent can discover endpoints and make real API calls.

Structure

api_mcp/
├── server.mjs                  # MCP server (stdio transport)
├── package.json
├── registry/
│   ├── index.json              # Root registry (lists services)
│   ├── service/
│   │   └── service.json        # Service definition (base URL, auth, hierarchy)
│   └── endpoints/
│       ├── index.json          # Endpoint index (15 endpoints)
│       └── *.json              # One file per endpoint (OpenAPI-derived)

Related MCP server: Relay

How it works

  1. server.mjs loads the registry JSON files at startup.

  2. It registers a tool for every endpoint in registry/endpoints/index.json (named by converting id to snake_case, e.g. create-spa-campaign → create_spa_campaign).

  3. Each endpoint tool accepts path params, query params, an optional body, plus x_token and x_retailer_id auth headers.

  4. Calling a tool performs the real HTTP request against https://apiv2.onlinesales.ai/marketing/v1/advertiser and returns status + parsed response.

Built-in tools

  • list_endpoints — list all endpoints (method, path, summary)

  • get_service_details — service definition (base URL, auth, hierarchy)

  • get_endpoint_definition — full schema for one endpoint by id

Resources

  • osmos://service — service definition

  • osmos://endpoints — endpoint index

Prompt

  • campaign-hierarchy — explains the campaign hierarchy before acting

Run

npm install
npm start

The server speaks MCP over stdio. Connect it from any MCP client (e.g. Claude Desktop, opencode) using:

{
  "mcpServers": {
    "osmos-marketing": {
      "command": "node",
      "args": ["/absolute/path/to/api_mcp/server.mjs"]
    }
  }
}

Auth

Every API call requires both headers — they are passed as x_token and x_retailer_id tool arguments:

x-token:        Authentication token
x-retailer-id:  Retailer identifier

Without both, the tool returns a clear error explaining they are required.

Adding a new endpoint

  1. Add registry/endpoints/<endpoint-id>.json following the existing schema pattern (fields: endpoint.id, method, path, operationId, summary, description, parameters, requestBody, responses, deprecated).

  2. Add an entry to registry/endpoints/index.json.

  3. Restart the server — the new endpoint tool is registered automatically.

Available Tools

18 tools
create_spa_campaignB

Create a new Sponsored Products Advertising (SPA) campaign. Creates a new SPA campaign with specified budget settings, bidding strategy, and campaign type. Supports AVERAGE_DAILY_BUDGET (default) and LIFETIME_BUDGET types.

Inputs: advertiser_id (required), body, x_token, x_retailer_id.

create_update_category_bids_for_campaignB

Create or update category bids for a campaign. Creates or updates the category bid settings for a campaign. When mode=MANUAL, the category_bids array is required. When mode=AUTO, the category_bids array is forbidden.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

create_update_negative_keyword_settings_for_campaignA

Create or update negative keyword settings for a campaign. Creates or updates negative keyword settings for a campaign. Each keyword entry is either a create (no id) or an update (id and status required; keyword, match_type, and bid_value forbidden). BROAD match type is not allowed for negative keyw

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

create_update_positive_keyword_settings_for_campaignB

Create or update positive keyword settings for a campaign. Creates or updates positive keyword settings for a campaign. Each keyword entry is either a create (no id) or an update (id required; keyword and match_type forbidden). To update a keyword, first fetch keywords via GET to obtain the keyword

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

create_update_product_set_for_campaignC

Create or update the product set for a campaign. Creates or updates the product set for a campaign. When products are selected within product sets, each product will function as an individual product ad. Supports AUTO mode (backend auto-selects products) and MANUAL mode (explicit product list).

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_campaign_forecastA

Get forecast for a campaign. Returns the forecast for a campaign based on its current or overridden budget. Forecasting is not supported for LIFETIME_BUDGET campaigns.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_campaign_network_settingsB

Get the networks a Sponsored Products campaign targets. Returns the networks a Sponsored Products campaign targets. A network is a retailer serving surface, such as a country-specific site or a storefront of the same retailer. A campaign with no saved network settings returns an empty networks array

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_category_bids_for_campaignA

Retrieve the category bids for a campaign. Returns the list of category bids for a campaign, including spend, revenue, ROI, current bid value, and allowed/recommended bid ranges.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_endpoint_definitionA

Get the full OpenAPI-derived definition for a specific endpoint by id (request/response schemas, params, examples).

Inputs: endpointId (required).

get_negative_keyword_settings_for_campaignA

Retrieve the negative keyword settings for a campaign. Returns the list of negative keywords for a campaign. Use this endpoint to fetch negative keyword ids before updating their status.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_positive_keyword_settings_for_campaignA

Retrieve the positive keyword settings for a campaign. Returns the list of positive keywords for a campaign. Use this endpoint to fetch keyword ids before updating keyword bids or status.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_product_set_for_campaignA

Retrieve the product set for a campaign. Returns the product set configured for a campaign. Response is either a MANUAL product set (with explicit product list) or an AUTO product set.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

get_service_detailsA

Get the OSMOS Marketing API service definition including base URL, authentication requirements, and campaign hierarchy.

Inputs: no named parameters.

get_spa_campaign_by_idA

Retrieve a specific SPA campaign by its ID. Returns the campaign details including budget settings, bidding strategy, dates, and status.

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

list_endpointsA

List all available API endpoints in the OSMOS Marketing API registry with their methods and paths.

Inputs: no named parameters.

list_spa_campaignsA

List all SPA campaigns for an advertiser with pagination and optional status filter. Returns a paginated list of campaigns. Supports filtering by status (ACTIVE, PAUSED). Offset and limit are required for pagination.

Inputs: limit (required), offset (required), advertiser_id (required), body, +3 more.

save_campaign_network_settingsA

Save the networks a Sponsored Products campaign targets. Saves the networks a Sponsored Products campaign targets. Each call replaces the previously saved set; include every network the campaign should target. A campaign_id that does not exist for the advertiser returns 404 with code RESOURCE_NOT_FO

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

update_spa_campaignA

Update an existing SPA campaign. All fields are optional — send only the fields you want to change. To change the campaign's bidding strategy, send bidding_strategy.type. Switches are only allowed within the same bid-mode family — CPC family: MANUAL_CPC, MAX_PERFORMANCE_CPC, ROAS; CPM family: MANUAL

Inputs: campaign_id (required), advertiser_id (required), body, x_token, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 18 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, from API introspection to campaign and sub-resource management. Even the create_update tools are clearly separated by resource type (product set, keywords, category bids).

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (create_, list_, get_, update_), but 'save_campaign_network_settings' breaks the pattern by using 'save' instead of 'create_update'. The combined 'create_update' verbs are somewhat unusual but applied consistently.

    Tool Count3/5

    At 18 tools, the server is within the 16-25 range that feels heavy per calibration. Each tool covers a specific endpoint, but the count is on the higher end for an MCP server.

    Completeness4/5

    The tool set covers the campaign lifecycle and all major sub-entities (product sets, keywords, bids, networks, forecast) well. However, there is no delete_campaign tool, which is a notable gap for a CRUD-like surface.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 35 MCP tools for automated marketing campaigns, integrating event management, booking, and email marketing into a deterministic pipeline for AI agents.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access a unified catalog of tools from various APIs (OpenAPI, GraphQL, MCP, Google Discovery) through the MCP protocol.
      12 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to perform go-to-market workflows such as company and contact enrichment, CRM querying, and controlled, audited writes to a CRM through MCP tools callable from any MCP client.
      1
      MIT