Skip to main content
Glama
gametheory-mcp
by ryuxik

gametheory-mcp

mcp-name: io.github.ryuxik/gametheory-mcp

Equilibrium-aware primitives for AI agents — negotiation, auctions, mechanism design — exposed over MCP and importable as a Python library.

LLMs are structurally bad at multi-round, opponent-modeling problems with closed-form solutions. This package gives them the math.

PyPI License: Apache 2.0

Install

pip install gametheory-mcp

Related MCP server: DiviDen MCP Server

Use it as an MCP server

Add to your MCP-aware client config (Claude Desktop, etc.):

{
  "mcpServers": {
    "gametheory": {
      "command": "gametheory-mcp"
    }
  }
}

The server is stdio-only. 13 tools across three tiers:

  • Tier 1 — Negotiation: gt_negotiation_sell_next_offer, gt_negotiation_buy_next_offer, gt_negotiation_detect_anchor_attack

  • Tier 2 — Auctions: gt_auction_optimal_bid, gt_auction_optimal_reserve, gt_auction_format_recommendation, gt_auction_simulate

  • Tier 3 — Mechanism Design: gt_mechanism_gale_shapley, gt_mechanism_optimal_auction_design, gt_mechanism_posted_price_optimal

Use it as a library

from gametheory_mcp.negotiation import sell_next_offer
from gametheory_mcp.auctions import optimal_bid
from gametheory_mcp.mechanism import gale_shapley

# Sell-side next-offer recommendation
rec = sell_next_offer(
    my_reservation=0.4,
    opponent_offer_history=[0.6, 0.55],
    my_offer_history=[0.85],
    deadline_rounds=8,
    pareto_knob=0.5,  # 0=max deal rate, 1=max margin
)
# → {recommended_offer, acceptance_probability, expected_payoff, ...}

# Vickrey is dominant-strategy truthful
bid = optimal_bid(
    auction_format="second_price_vickrey",
    my_valuation=0.7,
    n_competing_bidders=3,
    competitor_value_prior={"family": "uniform",
                             "params": {"low": 0, "high": 1}},
)
# → {optimal_bid: 0.7, dominant_strategy: True, ...}

What's in the package

The math primitives — Rubinstein 1982 SPE, Myerson 1981 optimal auction, Gale-Shapley deferred acceptance, Bayesian particle filter for opponent WTP inference. Empirical Pareto frontier data and tournament-tuned parameters are bundled in gametheory_mcp/_data/.

What's NOT in the package

The hosted API at https://api.snhp.dev adds:

  • Cryptographic first-strike commit-reveal for buy-side defense (requires server-side EdDSA keys + global commitment ledger; can't run cleanly in a stdio MCP process)

  • Vertical-specific Bayesian priors that warm-start new agents from the opt-in telemetry corpus

  • GDPR-compliant data export and deletion for the corpus

The hosted API is free for math endpoints (600 requests/min per key). Self-serve key issuance at POST https://api.snhp.dev/v1/keys.

Empirical anchor

SNHP — the negotiation strategy this package wraps — was rank #1 of 21 in a NegMAS round-robin tournament against well-known programmatic opponents (Aspiration, Anchorer, BATNA Bluffer, etc.). Statistically beats Aspiration (p=0.011), Split-the-Diff (p=0.014), Fair Demand (p<0.001).

Live leaderboard with LLM baselines: https://snhp.dev

License

Apache 2.0. See LICENSE.

Available Tools

10 tools
gt_auction_format_recommendationC

Recommend format from {first_price, vickrey, english} given weights.

Inputs: bidder_value_prior (required), n_bidders (required), seller_valuation (required), weights.

gt_auction_optimal_bidC

Optimal bid for {first_price | second_price_vickrey | english_ascending}. Vickrey is truthful. First-price uses the BNE for symmetric IPV.

Inputs: auction_format (required), my_valuation (required), n_competing_bidders (required), competitor_value_prior (required), +2 more.

gt_auction_optimal_reserveC

Myerson optimal reserve from virtual-value-equal-seller-valuation.

Inputs: bidder_value_prior (required), n_bidders (required), seller_valuation (required).

gt_auction_simulateC

Monte Carlo auction revenue + efficiency.

Inputs: auction_format (required), bidder_priors (required), reserve_price (required), n_simulations, +1 more.

gt_mechanism_gale_shapleyA

Stable matching via deferred acceptance. Proposers/receivers each have {id, preferences} (and optional capacity for receivers). Returns a proposer-optimal stable matching plus a blocking-pair sanity check.

Inputs: proposers (required), receivers (required).

gt_mechanism_optimal_auction_designC

Myerson revenue-optimal mechanism for asymmetric IPV. Per-bidder reserves; collapses to second-price-with-reserve under symmetric IPV.

Inputs: bidder_priors (required), seller_valuation (required), objective, n_simulations, +1 more.

gt_mechanism_posted_price_optimalC

Gallego-van Ryzin posted-price (static p* + dynamic backward-DP schedule).

Inputs: buyer_arrival_prior (required), arrival_rate_per_second (required), inventory (required), horizon_seconds (required), +2 more.

gt_negotiation_buy_next_offerC

Buy-side next-offer recommendation with a defense bundle. If anchor_attack_detection is in defenses, supply market_prior {mu, sigma}. Returns recommended offer + warnings + defense actions.

Inputs: my_reservation (required), seller_offer_history (required), my_offer_history (required), deadline_rounds (required), +3 more.

gt_negotiation_detect_anchor_attackA

Z-score the opponent's opening offer against a market prior {mu, sigma}. Recommends ignore / counter_with_market / walk_away.

Inputs: opponent_offer_history (required), market_prior (required).

gt_negotiation_sell_next_offerA

Sell-side next-offer recommendation. pareto_knob ∈ [0, 1] interpolates between deal-rate-max (0) and H2H-margin-max (1). Returns the recommended offer (in our utility space), acceptance probability, expected payoff, and the inferred posterior over the buyer's WTP.

Inputs: my_reservation (required), opponent_offer_history (required), my_offer_history (required), deadline_rounds (required), +2 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 10 tools

    Disambiguation5/5

    All tools have clearly distinct purposes: auction tools handle format, bidding, reserve, and simulation; mechanism tools cover matching, optimal auctions, and posted prices; negotiation tools handle buy/sell offers and attack detection. No overlap or ambiguity.

    Naming Consistency5/5

    Tools follow a strict 'gt_domain_action' pattern (e.g., gt_auction_optimal_bid, gt_negotiation_sell_next_offer). Naming is descriptive and uniform across all three domains.

    Tool Count5/5

    10 tools is well-proportioned for the server's scope: 4 auction, 3 mechanism, 3 negotiation. Each tool serves a specific, non-redundant function.

    Completeness4/5

    Covers core game theory mechanisms (auctions, matching, posted price, negotiation). Minor gaps exist, such as absence of common bargaining protocols or other auction formats (e.g., Dutch auction).

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Negotiation math engine for AI agents. Computes Pareto frontiers, generates iso-utility counteroffers, and infers counterpart priorities. 9 tools for any multi-issue negotiation. Zero LLM tokens — pure MILP optimization.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables autonomous multi-turn negotiation by calculating the Zone of Possible Agreement, modeling concession decay curves, enforcing reservation price thresholds, and generating structured bargaining counter-offers. It supports agentic commerce and contract negotiation workflows through a native MCP interface.
      7
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run automated Rubinstein alternating-offers bargaining and multi-item bundling negotiations with merchant gateways over MCP STDIO JSON-RPC. Supports game-theoretic surplus splitting and agentic commerce negotiation workflows.
      7
      MIT