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.

Install

pip install gametheory-mcp

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.