litvm-tcg-oracle
You can use this MCP server as a TCG price oracle for search, pricing, on-chain verification, risk forecasting, simulation, and oracle/market status.
Search 433K+ trading card products by name, with optional game filters and result limits.
Get current market/low prices and daily price history by card name or TCGPlayer product ID.
Fetch Merkle proofs to verify actively priced card prices on-chain on LitVM LiteForge.
Read live on-chain oracle status, including Merkle root, TWAP updates, and database stats.
Get calibrated conformal risk forecasts with VaR bands and Safe-Hold/Momentum grades.
Run Monte Carlo GBM/Merton price simulations using calibrated market data and risk metrics.
View top cards by value for a selected game via market snapshot, though the README notes this endpoint may be suspended/frozen.
Provides on-chain verification of trading card prices against the LitecoinVM blockchain, enabling AI agents to cryptographically prove price integrity via Merkle proofs.
π Connect over MCP β one URL, no install
https://litvm.the-undesirables.com/mcpNo install, no account, no API key. 16 tools over streamable HTTP β all free.
The full oracle through the LitVM lens: prices, on-chain Merkle proofs (raw AND
graded slabs), calibrated forecasts with a public accuracy scorecard, card-collateral
loan-terms previews, sports boards, the slab census, and the 4,444-soul fantasy
league whose weekly lineups are committed to the PredictionRegistry on LiteForge
before games score. Paid endpoints (full loan quotes, per-player sports forecasts)
live on the flagship oracle at https://mcp.the-undesirables.com via x402.
Claude Desktop / Perplexity β add it as a custom remote connector (Perplexity: Settings β Connectors β + Custom Connector β Remote).
Cursor / Windsurf / VS Code β clients that take a URL in config:
{
"mcpServers": {
"tcg-oracle": { "url": "https://mcp.the-undesirables.com" }
}
}Tools include search_tcg_products, card_forecast, simulate_price,
recommend_workflow and oracle_scorecard β call tools/list for the live set.
Everything is free: pay-per-call has been paused since 2026-10-02, and AI grading is retired.
Search is set-aware β search_tcg_products("Base Set Charizard") separates Base Set,
Base Set 2, and Shadowless rather than returning every Charizard printing. Every result
carries a set field and a product_id you can pass straight to the other tools.
Related MCP server: Sports Trading Card Agent
π Table of Contents
Why This Exists
AI agents are making decisions with market data β but how do they know the data is real?
Regular APIs require trust. You call an endpoint, you get a number, and you hope it's accurate. There's no way to verify it. For AI agents managing portfolios, executing trades, or assessing collateral, this is a problem.
This MCP server solves it. Every actively-priced product in the oracle is committed to a Merkle root on-chain daily β the USD root last advanced 2026-09-07 (feed frozen) and stays verifiable; Japanese, graded and sports panels advance daily. Any agent can request a Merkle proof for any card and independently verify the price against the LitVM LiteForge blockchain β no trust required.
What Makes This Different
Feature | Regular Price API | LitVM TCG Oracle |
Data source | Opaque server | 13.5M+ verified market observations |
Verification | Trust the server | Merkle proof β on-chain verification |
Forecasting | None | Calibrated conformal risk forecast β honest VaR |
Coverage | Limited | 455K products, 290K actively priced |
For AI agents | Manual integration | MCP β works in Claude, GPT, Cursor |
Blockchain | None | LitVM LiteForge |
Data Coverage
The oracle indexes the full TCGPlayer catalog and tracks live market prices:
Metric | Count | Description |
Total catalog | 446,694 | All products across 25+ games and 85 categories |
Actively priced | 276,788 | Products with a current |
Price observations | 13.5M+ | Daily snapshots collected over months |
Merkle-provable | 276,788 | Only actively-priced products are committed on-chain |
Zero-price entries | ~157K | Tokens, promos, bundles, foreign-market-only β searchable but not provable |
Transparency note: Not every product in the catalog has a market price. ~157K entries are catalog metadata with no trading activity (token cards, unopened case listings, foreign-language promos, etc.). These are returned by
search_cardsbut will return a404fromget_merkle_proofbecause zero-price products are not committed to the Merkle tree. This is by design β you wouldn't commit unverifiable data on-chain.
Quick Start
Install
pip install litvm-tcg-oracleFor live on-chain contract reads (optional):
pip install litvm-tcg-oracle[chain]Claude Desktop
Add to ~/.claude/claude_desktop_config.json:
{
"mcpServers": {
"litvm-tcg-oracle": {
"command": "litvm-tcg-oracle"
}
}
}Cursor / VS Code
Add to your MCP settings:
{
"litvm-tcg-oracle": {
"command": "litvm-tcg-oracle"
}
}Then ask your AI: "Search for Charizard Base Set and simulate the price over 90 days"
Tools
16 tools β seven core (below) plus nine ecosystem tools added in v1.1.0: get_graded_proof (GradedPriceOracle slab proofs on Chain 4441), get_fantasy_league (souls' lineups, merkle-locked on LiteForge weekly), get_oracle_scorecard (the public 30-day coverage record β verify before trusting), get_loan_terms_preview (six-step max-LTV derivation for card collateral), get_sports_board (daily movers over on-chain-committed stat panels), and get_census_summary (cert-verified circulating slab supply).
1. search_cards β Full-Text Search
Search the full 455K product catalog using FTS5 full-text search.
β search_cards(query="black lotus", game="Magic", limit=5)Covers 25+ games including: PokΓ©mon, Magic: The Gathering, Yu-Gi-Oh!, One Piece, Disney Lorcana, Flesh & Blood, Dragon Ball Super, Digimon, Star Wars, Union Arena, MetaZoo, Cardfight Vanguard, My Hero Academia.
Returns product IDs needed for get_price and get_merkle_proof.
2. get_price β Price + History
Get current market price and daily price history for any card.
β get_price(card_name="Charizard Base Set Holo", days=90)Returns market price, low (buy-it-now) price, and a daily price array. This history is what powers the risk-forecast calibration β the same data the forecast engine uses to calculate drift, volatility, and conformal bands.
3. get_merkle_proof β On-Chain Verification
This is the key differentiator. Get a cryptographic proof that a card's price was committed to the LitVM LiteForge blockchain.
β get_merkle_proof(product_id=84198)Returns a bytes32[] proof array (19 hashes for the current tree) that can be submitted to the MerklePriceOracle contract on LitVM LiteForge to verify the price without trusting any server.
Verification flow:
Call
get_merkle_proof(product_id)β receive proof + leaf dataSubmit to
MerklePriceOracle.verifyPrice()on LitVM LiteForgeContract checks the leaf against the committed Merkle root
Returns
trueif and only if the price matches exactly
Leaf encoding (matches Solidity):
keccak256(bytes.concat(keccak256(abi.encode(
productId, categoryId, name, marketPrice, lowPrice
))))Standard: OpenZeppelin MerkleProof (double-hash, sorted pairs)
Only the ~290K actively-priced products are in the Merkle tree. Zero-price catalog entries return a
404β this is correct behavior.
4. oracle_status β Live On-Chain Status
Reads directly from the LitVM LiteForge blockchain via the LiteForge RPC β not cached data.
β oracle_status()Returns:
MerklePriceOracle: Merkle root, total products, freshness, total root updates
TCGPriceOracleV2: Total TWAP updates, last update timestamp, 660+ confirmed updates
Database: Card count, price rows, latest data date
5. get_forecast β Conformal Risk Forecast
The recommended, honest default forecast. Distribution-free, deterministic, never-under-protective β calibrated on real cross-card price history, no distributional assumption.
β get_forecast(card_name="Charizard Base Set Holo")Returns the agent-complete forecast: price, as_of, regime, point estimate, expected 30-day move, prob_up, 50%/90% bands, VaR 95/99, a Safe-Hold grade (downside / capital preservation), a Momentum grade (direction β or "NA" on a recent drift spike), and a one-line plain_english read.
Why conformal? Honest VaR: out-of-sample, a "5% VaR" means a ~5% loss happens about 5% of the time. No Monte Carlo, fully deterministic, anyone can reproduce it. Calls the free /api/v1/forecast/{product_id} endpoint.
6. simulate_price β Monte Carlo Simulation (FROZEN INPUTS since 2026-09-07)
An opt-in stochastic view β Monte Carlo price paths (Merton/GBM) calibrated from real market data. The USD price series it calibrates on stopped 2026-09-07; responses carry usd_panel {frozen: true}. Say "last published", never "today". Use get_forecast for the honest default.
β simulate_price(card_name="Charizard Base Set", days=30, model="merton")How the Simulation Works
This is not placeholder math. Every simulation parameter is calibrated from real price observations stored in the oracle database.
Calibration Pipeline:
Card name β FTS5 search β product_id β price_history (up to 365 days)
β weekly resampling (ISO week buckets)
β log-returns between weekly closing prices
β annualized drift (ΞΌ) and volatility (Ο)
β jump detection via 2Ο threshold on time-scaled returns
β 10,000 vectorized numpy simulation paths
β percentile forecast bands + VaR/CVaR risk metricsWhy weekly resampling? Daily TCG prices have irregular gaps (weekends, holidays, no sales). Weekly resampling produces stable drift estimates by collapsing daily observations into ISO-week buckets and computing log-returns between weekly closing prices. This eliminates the βΞt scaling problem that plagues irregularly-spaced data.
Models (pass via model=, default merton):
For the calibrated conformal forecast (honest VaR + Safe-Hold/Momentum grades), use
get_forecastabove. The two models below are the stochastic Monte Carlo alternatives.
Geometric Brownian Motion (GBM)
dS = ΞΌΒ·SΒ·dt + ΟΒ·SΒ·dWStandard log-normal diffusion β the foundation of Black-Scholes option pricing. Assumes continuous price movements with no sudden jumps.
Merton Jump-Diffusion (default)
dS = (ΞΌ β Ξ»k)Β·SΒ·dt + ΟΒ·SΒ·dW + JΒ·SΒ·dNExtends GBM by adding Poisson-distributed price jumps to capture sudden market events β buyouts, influencer videos, ban lists, set reprints, tournament results.
Symbol | Meaning | Calibration |
| Drift (annualized return) | Weekly log-return mean Γ 52 |
| Volatility | Weekly log-return stdev Γ β52 |
| Jump intensity (jumps/year) | Count of returns > 2Ο, annualized |
| Jump mean | Average of detected jump returns |
| Jump volatility | Stdev of detected jump returns |
| Drift compensator |
|
| Brownian motion | Standard Wiener process |
| Jump arrival | Poisson(λ·dt) |
Risk Metrics:
VaR 95%: "There is a 5% chance the price drops below $X over N days"
CVaR 95% (Expected Shortfall): "If that tail event occurs, the average loss lands at $Y"
Transparency:
param_source: "calibrated_from_market_data"β real parameters from this card's historyparam_source: "default_tcg_priors"β insufficient data (<5 points), using conservative priors (3% drift, 40% vol)Standard errors reported for ΞΌ, Ο, Ξ» to quantify parameter uncertainty
Mean-reversion detection via lag-1 autocorrelation
References:
Merton, R.C. (1976). Option pricing when underlying stock returns are discontinuous. Journal of Financial Economics, 3(1-2), 125-144.
Black, F. & Scholes, M. (1973). The Pricing of Options and Corporate Liabilities. Journal of Political Economy, 81(3), 637-654.
6. get_market_snapshot β Market Overview
SUSPENDED 2026-09-12 β
/api/v1/marketis suspended while the USD panel is frozen; the oracle answers{"status": "suspended"}with live alternatives and does not charge.
Top cards by value for any game.
β get_market_snapshot(game="Pokemon", limit=25)Architecture
ββββββββββββββββββββ MCP (stdio) ββββββββββββββββββββββββ
β β βββββββββββββββββββββββΊ β β
β AI Agent β β litvm-tcg-oracle β
β (Claude, GPT, β β MCP Server β
β Cursor, etc.) β β (pip install) β
β β β β
ββββββββββββββββββββ ββββββββ¬ββββββββ¬ββββββββ
β β
HTTPS β β RPC
β β
βΌ βΌ
ββββββββββββββββββββ βββββββββββββββ
β Oracle REST API β β LitVM LiteForge β
β (Mac Mini) β β LitVM LiteForge β
β β β β
β 455K products β β Merkle + β
β 13.5M prices β β V2 Oracle β
β FTS5 search β β contracts β
ββββββββββββββββββββ βββββββββββββββOff-chain layer (REST API): Search, prices, market data, simulation calibration
On-chain layer (LitVM LiteForge RPC): Merkle root verification, oracle contract status, TWAP feeds
The Mac Mini runs the daily pipeline (scrape β price update β Merkle root β on-chain push) and serves the REST API. The MCP server is a thin client that any developer can pip install and connect to Claude, GPT, or Cursor.
Configuration
Variable | Default | Description |
|
| Override the API base URL |
|
| Override the LiteForge RPC used for on-chain reads |
Local Development
export LITVM_ORACLE_URL=http://localhost:8402
litvm-tcg-oracleOn-Chain Contracts
Contract | Address | Purpose |
MerklePriceOracle | Merkle root for 290K products (USD feed frozen 2026-09-07 β root no longer advances, still verifiable) | |
TCGPriceOracleV2 | Hourly TWAP updater for top 50 blue-chip cards (feed has not moved since 2026-09-07) |
Both contracts are deployed on LitVM LiteForge testnet (Chain ID 4441) via the LiteForge RPC.
π License & Commercial Use
This project is licensed under the Business Source License 1.1 (BUSL-1.1).
We build in public and support the developer ecosystem β but we also protect the infrastructure and IP of The Undesirables LLC.
β What You CAN Do (Free)
Personal & Educational Use β Download, modify, and run locally for learning, research, or personal projects.
Non-Competing Applications β Integrate this MCP server into your app, provided your app does not offer TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle services as its primary function.
MCP / Agent Integration β Connect your AI agent to this server for non-commercial use.
Community Contributions β Security audits, bug fixes, and PRs are always welcome.
π« What You CANNOT Do (Use Limitation)
Competing Oracle β You may not use this code to operate a competing price oracle service on LitVM LiteForge or any compatible chain.
Commercial Resale β You may not wrap our API, data pipelines, or AI models into a paid service without a commercial license.
Hosted SaaS β You may not host this software as a service for third parties without written permission.
π Open-Source Conversion
On June 1, 2030 (or 4 years after the first public release of each version), this code automatically converts to the MIT License β fully open source, forever.
π€ Commercial Licensing
Building a commercial product? Want guaranteed API access or white-label integration? Contact us:
π§ oracle@the-undesirables.com Β· π¦ @undesirables_ai
Β© 2026 The Undesirables LLC
Links
Website: the-undesirables.com
Oracle API: oracle.the-undesirables.com
LitVM LiteForge: explorer.testnet.liteforge.zeeve.net
Block Explorer: explorer.testnet.liteforge.zeeve.net
Built by The Undesirables LLC β the first and only oracle on LitVM LiteForge.
β If this project helped you, please star this repo β it helps others find it.
Available Tools
7 toolsget_forecastA
Get the calibrated conformal risk forecast for a trading card.
This is the recommended, honest default forecast β distribution-free, deterministic, and never-under-protective. Unlike a Monte Carlo simulation it makes NO distributional assumption: the bands are calibrated on real cross-card price history, so the stated risk is honest out-of-sample (a "5% VaR" means a ~5% loss happens about 5% of the time). Each card also gets two plain-English letter grades.
Inputs: card_name (required). Returns: result
get_market_snapshotA
Get a market overview β top trading cards sorted by value.
Returns the highest-value cards for a specific game with current market prices and low (buy-it-now) prices.
Games: Pokemon, Magic, Yu-Gi-Oh, One Piece, Disney Lorcana, Flesh and Blood, Dragon Ball Super, Digimon, Star Wars, Union Arena, MetaZoo, Cardfight Vanguard, My Hero Academia.
Inputs: game, limit. Returns: result
get_merkle_proofA
Get a Merkle proof for on-chain price verification on LitecoinVM.
WHY THIS MATTERS FOR AI AGENTS: Regular API prices require trusting the server. Merkle proofs let you VERIFY the price on-chain without trusting anyone. The proof is a cryptographic guarantee that this exact price was committed to the LitecoinVM blockchain by the oracle operator.
The TCG Price Oracle commits 276K actively-priced products to a single Merkle root on LiteForge daily. This tool returns the proof array that can be submitted to the MerklePriceOracle smart contract to trustlessly verify any card's price.
NOTE: Only actively-priced products (market_price > 0) are included in the Merkle tree. Zero-price catalog entries cannot be proven.
Inputs: product_id (required). Returns: result
get_priceA
Get the latest market price and historical price data for a trading card.
Provide either a card name (fuzzy search) or a TCGPlayer product ID. Returns current market price, low (buy-it-now) price, and daily price history for the requested time window.
The price history is what powers the Monte Carlo simulation β it's the same data used to calibrate drift and volatility parameters.
Inputs: days, card_name, product_id. Returns: result
oracle_statusA
Get live status of the TCG Price Oracle on LitecoinVM.
Reads DIRECTLY from the LiteForge blockchain (Chain ID 4441) via the Caldera RPC endpoint β this is NOT cached data, it's a live on-chain read at the moment you call it.
Returns: β’ MerklePriceOracle: current root, total products, freshness, update count β’ TCGPriceOracleV2: total TWAP updates, last update timestamp β’ Network: connection status, chain ID, RPC URL, explorer link β’ Database: card count, price rows, latest data date (from API)
No arguments required.
Inputs: no named parameters. Returns: result
search_cardsA
Search 433K+ trading card products by name using full-text search.
The catalog contains 433K products total β 276K are actively priced with current market data. ~157K are catalog-only entries (tokens, promos, bundles) with no price history. Disney Lorcana, Flesh & Blood, Dragon Ball Super, Digimon, Star Wars, Union Arena, MetaZoo, Cardfight Vanguard, and My Hero Academia.
Returns product IDs (needed for get_price and get_merkle_proof), card names, games, and current market prices.
Inputs: query (required), game, limit. Returns: result
simulate_priceA
Run a Monte Carlo price simulation for a trading card (opt-in).
For the honest DEFAULT forecast β conformal VaR + Safe-Hold/Momentum grades β use get_forecast. This tool is the stochastic Monte Carlo alternative (Merton/GBM).
HOW THE MATH WORKS: This is NOT fake data. The simulation calibrates parameters from REAL market prices stored in the oracle database (12.7M+ price observations):
Look up the card β get product_id via FTS5 search
Pull up to 365 days of daily price history
Resample to weekly buckets for stable drift estimates
Compute annualized drift (ΞΌ) and volatility (Ο)
Detect price jumps via 2Ο threshold on time-scaled returns
Run 10,000+ vectorized numpy simulation paths
Return percentile forecast bands + risk metrics
If insufficient price history exists (<5 data points), conservative TCG market priors are used (3% drift, 40% vol) and clearly labeled as "default_tcg_priors" in the response.
Inputs: card_name (required), days, model, simulations. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 7 tools
Most tools target clearly distinct resources: search, pricing, proof verification, status, and market snapshot. The only potential confusion is between get_forecast and simulate_price, which both produce risk forecasts, but their descriptions explicitly differentiate the deterministic conformal approach from the stochastic Monte Carlo alternative.
The naming pattern is largely consistent with snake_case verb_noun names like get_price, get_forecast, and search_cards. The minor deviation is oracle_status, which is a noun_noun name and does not follow the get_ prefix used by most other tools.
Seven tools is well-scoped for a TCG price oracle server. Each tool serves a distinct need: discovery, price data, cryptographic verification, status monitoring, forecasting, simulation, and market overview, with no redundancy or bloat.
The tool surface covers the full user journey for the oracle domain: search for a card, get its price, verify the price on-chain via Merkle proof, check oracle health, and obtain risk forecasts. The inclusion of both a deterministic forecast and a stochastic simulation fills the major analytical needs, and no critical missing operation is apparent.
Maintenance
Related MCP Connectors
TCG oracle: calibrated prices & risk, AI grading, loan terms, fantasy souls - proven on-chain. 23 to
Trading card prices and grading ROI for 1.5M+ PokΓ©mon, Magic, Yu-Gi-Oh! and sports cards. Read-only.
Live TCG card and decklist prices for AI assistants. 22+ games, no account, ready-to-buy links.
Values graded sports cards and PokΓ©mon/TCG slabs by grade from real sales. Free, read-only.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server providing Ethereum blockchain tools, including vanity address generation and Cast command functionality for interacting with Ethereum networks through natural language.14MIT
- AlicenseAqualityDmaintenanceReal-time sports card pricing, market analysis, arbitrage detection, grading ROI, investment advice, and player stats (NBA/NFL/MLB). 9 tools for AI agents helping collectors and investors.929 PyPI3MIT
- AlicenseAqualityDmaintenanceA read-only MCP server that wraps the coffee.pryzm.gg public API to calculate effective prices of coffee drinks after discounts, enabling users to find the cheapest coffee deals, search for discounts, and verify receipt prices.32MIT
- FlicenseNot gradedqualityDmaintenanceProvides access to TCGplayer trading card data, including search, product details, pricing, and market information, enabling natural language queries for card analysis.1-