Polymarket MCP Tool

Instructions

Implementation Reference

• main.py:27-60 (handler)

  MCP tool handler function for prediction_markets_markets_by_topic. Decorated with @mcp.tool for registration. Fetches markets using poly.markets_by_topic and returns JSON string.

  @mcp.tool
  async def prediction_markets_markets_by_topic(topic_slug: str, limit: int = 10) -> str:
      """
      Call after you have a Polymarket topic slug (from the user or
      `prediction_markets_trending_topics`) and need the top markets under it.
  
      Parameters
      ----------
      topic_slug : str
          Identifier such as "trump-presidency".
      limit : int, default 10
          Number of markets to return, ranked by 24-hour volume (desc).
  
      Returns
      -------
      str
          JSON array of objects with the schema:
          [
            {
              "title": "Trump to win 2024?",
              "volume": 123456.78,
              "outcomes": [
                {"option": "Yes", "probability": 0.42},
                {"option": "No",  "probability": 0.58}
              ]
            },
            …
          ]
          Parse with `json.loads`.
      """
  
      markets = await poly.markets_by_topic(topic_slug, limit)
      return json.dumps([m.model_dump() for m in markets])

• polymarket.py:8-17 (schema)

  Pydantic models defining the structure of market outcomes and markets returned by the tool.

  class MarketOutcome(BaseModel):
      option: str
      probability: float
  
  
  class Markets(BaseModel):
      title: str
      volume: float
      outcomes: list[MarketOutcome]

• polymarket.py:32-82 (helper)

  Helper function that scrapes Polymarket webpage to derive topic slug and queries the API for markets by topic, returning structured Markets objects.

  async def markets_by_topic(tab_name: str, limit: int = 10) -> list[Markets]:
      async with async_playwright() as p:
          browser = await p.chromium.launch(headless=True)
          page = await browser.new_page()
          await page.goto("https://polymarket.com", wait_until="domcontentloaded")
  
          tab = page.get_by_role("tab", name=tab_name)
          slug_full = await tab.get_attribute(
              "aria-controls"
          )  # e.g. radix-:r6p:-content-big-beautiful-bill
          if not slug_full:
              raise ValueError(f"Tab '{tab_name}' not found or has no slug.")
  
          tag_slug = slug_full.split("-content-")[-1]  # → 'big-beautiful-bill'
  
          # build the API URL
          base = "https://gamma-api.polymarket.com/events/pagination"
          query = dict(
              limit=limit,
              active="true",
              archived="false",
              tag_slug=tag_slug,
              closed="false",
              order="volume24hr",
              ascending="false",
              offset=0,
          )
          url = f"{base}?{urlencode(query)}"
  
          data = requests.get(url, timeout=15).json()["data"]
          res: list[Markets] = []
          for e in data:
              try:
                  outcomes = [
                      MarketOutcome(
                          option=outcome,
                          probability=float(price),
                      )
                      for outcome, price in zip(
                          json.loads(e["markets"][0]["outcomes"]),
                          json.loads(e["markets"][0]["outcomePrices"]),
                      )
                  ]
                  res.append(
                      Markets(title=e["title"], volume=e["volume"], outcomes=outcomes)
                  )
              except Exception as ex:
                  print(e["markets"][0])
                  raise ex
  
          return res

• main.py:27-27 (registration)

  The @mcp.tool decorator registers the function as an MCP tool.

  @mcp.tool