The first Model Context Protocol server for the LitecoinVM (LitVM) ecosystem.
Plug any AI agent into 455K+ real trading card prices across 25+ games β every price backed by on-chain Merkle proofs, not blind trust.
## π Connect over MCP β one URL, no install
```
https://litvm.the-undesirables.com/mcp
```
No 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:
```json
{
"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.
---
## π Table of Contents
- [Connect over MCP](#-connect-over-mcp--one-url-no-install)
- [Why This Exists](#why-this-exists)
- [Data Coverage](#data-coverage)
- [Quick Start](#quick-start)
- [Tools](#tools)
- [search_cards](#1-search_cards--full-text-search)
- [get_price](#2-get_price--price--history)
- [get_merkle_proof](#3-get_merkle_proof--on-chain-verification)
- [oracle_status](#4-oracle_status--live-on-chain-status)
- [get_forecast](#5-get_forecast--conformal-risk-forecast)
- [simulate_price](#6-simulate_price--monte-carlo-simulation)
- [get_market_snapshot](#7-get_market_snapshot--market-overview)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [On-Chain Contracts](#on-chain-contracts)
- [License & Commercial Use](#-license--commercial-use)
- [Links](#links)
---
## 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 `market_price > 0` |
| **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_cards` but will return a `404` from `get_merkle_proof` because 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
```bash
pip install litvm-tcg-oracle
```
For live on-chain contract reads (optional):
```bash
pip install litvm-tcg-oracle[chain]
```
### Claude Desktop
Add to `~/.claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"litvm-tcg-oracle": {
"command": "litvm-tcg-oracle"
}
}
}
```
### Cursor / VS Code
Add to your MCP settings:
```json
{
"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:**
1. Call `get_merkle_proof(product_id)` β receive proof + leaf data
2. Submit to `MerklePriceOracle.verifyPrice()` on LitVM LiteForge
3. Contract checks the leaf against the committed Merkle root
4. Returns `true` if 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 Caldera 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 metrics
```
**Why 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_forecast`](#5-get_forecast--conformal-risk-forecast) above. The two models below are the stochastic Monte Carlo alternatives.
**Geometric Brownian Motion (GBM)**
```
dS = ΞΌΒ·SΒ·dt + ΟΒ·SΒ·dW
```
Standard 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Β·dN
```
Extends 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 |
| `k` | Drift compensator | `E[eα΄Ά] - 1` (ensures fair pricing) |
| `dW` | Brownian motion | Standard Wiener process |
| `dN` | 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 history
- `param_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/market` is 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 |
|----------|---------|-------------|
| `LITVM_ORACLE_URL` | `https://oracle.the-undesirables.com` | Override the API base URL |
### Local Development
```bash
export LITVM_ORACLE_URL=http://localhost:8402
litvm-tcg-oracle
```
---
## On-Chain Contracts
| Contract | Address | Purpose |
|----------|---------|---------|
| **MerklePriceOracle** | [`0x96B124...170Cd`](https://liteforge.explorer.caldera.xyz/address/0x96B124f50156589274ADF8F674509374752170Cd) | Merkle root for 290K products (USD feed frozen 2026-09-07 β root no longer advances, still verifiable) |
| **TCGPriceOracleV2** | [`0x697bF6...720E`](https://liteforge.explorer.caldera.xyz/address/0x697bF6AE96fb05a47106abd012C39855A16a720E) | 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 [Caldera RPC](https://liteforge.rpc.caldera.xyz/http).
---
## π License & Commercial Use
This project is licensed under the **[Business Source License 1.1 (BUSL-1.1)](https://github.com/sailorpepe/litvm-tcg-oracle-mcp/blob/main/LICENSE.md)**.
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](https://x.com/undesirables_ai)**
Β© 2026 The Undesirables LLC
---
## Links
- **Website**: [the-undesirables.com](https://the-undesirables.com)
- **Oracle API**: [oracle.the-undesirables.com](https://oracle.the-undesirables.com)
- **LitVM LiteForge**: [liteforge.explorer.caldera.xyz](https://liteforge.explorer.caldera.xyz)
- **Block Explorer**: [liteforge.explorer.caldera.xyz](https://liteforge.explorer.caldera.xyz)
- **X**: [@undesirables_ai](https://x.com/undesirables_ai)
*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.
[Report Bug](../../issues) Β· [Request Feature](../../issues)