Wincher MCP by usefulapi

The Wincher account behind the token: id, timezone and the plan limits with current usage (websites, users, keywords, keyword lookups, map-tracking credits, history days). Check keyword usage here before adding keywords. GET /account.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The Wincher user the token belongs to: id, role, state, project access and profile (name, email, language). GET /user.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The search engines Wincher can track (id, domain such as google.com, country, languages, default location). GET /search-engines.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search the locations Wincher can track rankings for (code, name, country), most popular first, at most 100. Both are required by the API: an ISO country code and a free-text search (at least 3 characters). GET /locations.

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "minLength": 3,
      "maxLength": 100,
      "description": "Free text, at least 3 characters, e.g. 'new york' (required by the Wincher API)."
    },
    "country": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "ISO 3166-1 alpha-2 country code, e.g. US (required by the Wincher API)."
    }
  },
  "required": [
    "search",
    "country"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List projects (folders that group websites): id, name, website_ids, user_ids, and optionally the ranking summary for a period. GET /projects.

{
  "type": "object",
  "properties": {
    "order_by": {
      "description": "Field to order by; prefix with '-' for descending, e.g. 'keyword' or '-created_at'.",
      "type": "string",
      "pattern": "^-?[a-z][a-z0-9_.]{0,59}$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "offset": {
      "description": "Skip this many results (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the websites tracked in Wincher: id, domain, display name, search engine, location, language, mobile flag, keyword/group/competitor counts, competitors and brand keywords. Optionally with the ranking summary for a period. GET /websites.

{
  "type": "object",
  "properties": {
    "order_by": {
      "description": "Field to order by; prefix with '-' for descending, e.g. 'keyword' or '-created_at'.",
      "type": "string",
      "pattern": "^-?[a-z][a-z0-9_.]{0,59}$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "offset": {
      "description": "Skip this many results (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "include_serp_features": {
      "description": "Include serp_features in the ranking data. Default true; false makes replies much smaller and faster.",
      "type": "boolean"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One tracked website with its settings, competitors, brand keywords, counts and (for the period) ranking summary. GET /websites/{website_id}.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "include_serp_features": {
      "description": "Include serp_features in the ranking data. Default true; false makes replies much smaller and faster.",
      "type": "boolean"
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the keywords tracked for a website with groups, volume, CPC, difficulty, competition, search intents and, with include_ranking, the latest position, traffic, ranking pages, SERP features and best position in the period. Positions are tracked down to the top 30. GET /websites/{website_id}/keywords.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "order_by": {
      "description": "Field to order by; prefix with '-' for descending, e.g. 'keyword' or '-created_at'.",
      "type": "string",
      "pattern": "^-?[a-z][a-z0-9_.]{0,59}$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "offset": {
      "description": "Skip this many results (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One tracked keyword with its groups, volume, CPC, difficulty and (default) ranking for the period. GET /websites/{website_id}/keywords/{keyword_id}.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "keyword_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher keyword id (from wincher_list_keywords)."
    },
    "include_ranking": {
      "description": "Include ranking data. Default true; false is faster.",
      "type": "boolean"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id",
    "keyword_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The most recent search result pages Wincher stored for a keyword (up to 30): date, search volume, SERP features and the ranking results (position, URL, domain, traffic). GET /websites/{website_id}/keywords/{keyword_id}/serps.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "keyword_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher keyword id (from wincher_list_keywords)."
    }
  },
  "required": [
    "website_id",
    "keyword_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Historical position (or estimated traffic) for ONE keyword as time series, optionally split per ranking page or per competitor. GET /websites/{website_id}/keyword/{keyword_id}/ranking-history.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "keyword_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher keyword id (from wincher_list_keywords)."
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "metric": {
      "description": "Default position.",
      "type": "string",
      "enum": [
        "position",
        "traffic"
      ]
    },
    "group_by": {
      "description": "Split into one series per ranking page or per competitor.",
      "type": "string",
      "enum": [
        "page",
        "competitor"
      ]
    }
  },
  "required": [
    "website_id",
    "keyword_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Historical positions for up to 50 keywords at once (one time series per keyword). This is a read: it uses POST only because the keyword id list goes in the body. POST /websites/{website_id}/ranking-history.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "keyword_ids": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      },
      "description": "Keyword ids (1-50)."
    },
    "start": {
      "type": "string",
      "description": "Start of the period (date or ISO date-time, UTC)."
    },
    "end": {
      "type": "string",
      "description": "End of the period (date or ISO date-time, UTC)."
    }
  },
  "required": [
    "website_id",
    "keyword_ids",
    "start",
    "end"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the keyword groups of a website: id, name, keyword_ids, average difficulty, search-intent counts and optionally ranking summaries. GET /websites/{website_id}/groups.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "order_by": {
      "description": "Field to order by; prefix with '-' for descending, e.g. 'keyword' or '-created_at'.",
      "type": "string",
      "pattern": "^-?[a-z][a-z0-9_.]{0,59}$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "offset": {
      "description": "Skip this many results (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "include_serp_features": {
      "description": "Include serp_features in the ranking data. Default true; false makes replies much smaller and faster.",
      "type": "boolean"
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One keyword group with its keyword ids and (optionally) ranking summary for the period. GET /websites/{website_id}/groups/{group_id}.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "group_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Keyword group id (from wincher_list_groups)."
    },
    "include_ranking": {
      "description": "Include ranking data (slower and larger). Default false.",
      "type": "boolean"
    },
    "include_serp_features": {
      "description": "Include serp_features in the ranking data. Default true; false makes replies much smaller and faster.",
      "type": "boolean"
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id",
    "group_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The competitor domains tracked for a website (id, domain, created_at). GET /websites/{website_id}/competitors.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "order_by": {
      "description": "Field to order by; prefix with '-' for descending, e.g. 'keyword' or '-created_at'.",
      "type": "string",
      "pattern": "^-?[a-z][a-z0-9_.]{0,59}$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "offset": {
      "description": "Skip this many results (default 0). Pass the previous reply's next_offset.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000000
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Ranking summaries (average position, share of voice, traffic, position distribution, volume) for the website's competitors over a period, for comparison with your own. GET /websites/{website_id}/competitors/ranking-summaries.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "include_serp_features": {
      "description": "Include serp_features in the ranking data. Default true; false makes replies much smaller and faster.",
      "type": "boolean"
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

For each tracked keyword, the position of your site and of each competitor in the period. GET /websites/{website_id}/competitors/keyword-positions.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "segment_id": {
      "description": "Filter by a saved or temporary segment id (see wincher_list_segments).",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$"
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The annotations (notes on the ranking graphs: automatic, alert and user-written) for a website, optionally within a period. GET /websites/{website_id}/annotations.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "start": {
      "description": "Start of the period (date or ISO date-time, UTC).",
      "type": "string"
    },
    "end": {
      "description": "End of the period (date or ISO date-time, UTC).",
      "type": "string"
    }
  },
  "required": [
    "website_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The saved segments (keyword filters) usable as segment_id in other tools. By default also temporary ones; only_named limits to saved ones. GET /segments.

{
  "type": "object",
  "properties": {
    "only_named": {
      "description": "Only named (saved) segments. Default false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: start tracking up to 50 new keywords on ONE website. EACH keyword uses one keyword slot of the plan's keyword quota (see wincher_get_account), and it is tracked and updated from then on; this tool cannot remove keywords again. Each keyword may name a preferred_url (the landing page expected to rank). Invalid or already-tracked keywords are ignored by Wincher (not created). 'groups' are keyword group NAMES to put every keyword in (may be empty; use names from wincher_list_groups, an unknown name may create a new group). POST /websites/{website_id}/keywords/bulk.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "keywords": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "The search term to track."
          },
          "preferred_url": {
            "description": "Preferred landing page for this keyword.",
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "required": [
          "keyword"
        ]
      },
      "description": "1-50 keywords to add (each uses one keyword slot)."
    },
    "groups": {
      "description": "Keyword group names to assign to all of these keywords (default none).",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    }
  },
  "required": [
    "website_id",
    "keywords"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a keyword group on a website, optionally containing existing keywords (ids from wincher_list_keywords). Uses no keyword quota. POST /websites/{website_id}/groups.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Group name (1-200 characters)."
    },
    "keyword_ids": {
      "description": "Existing keyword ids to put in the group (default none).",
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "website_id",
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a user annotation (a note shown on the ranking graphs, e.g. 'Launched new landing page') for a date, optionally tied to specific keywords; without keyword_ids it is a global note for the website. Visible to everyone with access to the website. Uses no keyword quota. POST /websites/{website_id}/annotations.

{
  "type": "object",
  "properties": {
    "website_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Wincher website id (from wincher_list_websites)."
    },
    "date": {
      "type": "string",
      "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
      "description": "The date the note is shown at, yyyy-mm-dd."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "The note text."
    },
    "keyword_ids": {
      "description": "Keyword ids this note relates to; omit for a global note.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "website_id",
    "date",
    "description"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}