undesirables-mcp-server

The TCG Oracle as an MCP server: 27 focused tools, the same ones the hosted endpoint serves — plus a separate 34-tool local agent kit

Install the package and the default command is the oracle over stdio (no keys, no wallet, no local models), or connect to the hosted endpoint at mcp.the-undesirables.com. Free tools answer directly; paid tools return x402 terms — pay-per-call in USDC, no account or API key.

Website · Docs · PyPI · 𝕏

---

🔌 Connect over MCP — one URL, no install

https://mcp.the-undesirables.com

Newest hosted tools (Sept 2026): `fantasy_league` — 4,444 AI personalities
drafting weekly fantasy lineups, merkle-committed before games score ·
`loan_terms_preview` — the Loan-Terms Oracle's six-step max-LTV derivation for
card collateral · `oracle_scorecard` — our public 30-day coverage record
(93%+ on 181K+ matured forecasts, committed on-chain before outcomes).

No install, no account, no API key. 25 tools over streamable HTTP (MCP protocol 2025-06-18; legacy SSE also served). Free tools answer immediately. Paid tools return an x402 payment_required carrying amount, network, and payTo — an agent with a funded wallet can settle and retry in the same session. Settlement only occurs on a successful response; failed calls are never charged.

Holders can also ask which Undesirables a wallet owns and how each soul's calls have scored (souls_in_wallet, soul_calls) — public track record only; personalities stay holder-gated.

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: search_tcg_products, market_snapshot, simulate_price, card_forecast, trending_cards, optimize_portfolio, recommend_workflow, oracle_scorecard.

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.

---

Two servers, one package (v2.0.0)

Command	What it exposes	For
undesirables-mcp (default)	The TCG Oracle — 25 tools: search 456K+ cards (USD prices frozen 2026-09-07 — responses carry usd_panel), market snapshots (suspended while frozen), AI grading & grade-or-not, conformal-calibrated forecasts with a public accuracy scorecard, portfolio optimisation, card-collateral loan terms, fantasy & sports souls, the Syndicate, Technocore rooms. Backed by the public oracle API.	Anyone who wants the oracle in Claude Desktop, Cursor, Zed, LangChain…
undesirables-agent-kit	The local agent kit — 34 tools: memory graph, RAG over a soul workspace, meme/banner/video/3D generation, voice, code & shell execution, security audits, web search. Runs entirely on your machine.	Undesirables holders running their soul as a local agent

v1.x shipped both surfaces under one command; v2 separates them so each server has one job. The hosted endpoint is unchanged.

Quick Install

pip install undesirables-mcp-server

undesirables-mcp          # the TCG Oracle over stdio (25 tools, no keys) — default
undesirables-agent-kit    # the local 34-tool agent kit

Claude Desktop / Cursor / Zed — add the oracle as a stdio server:

{ "mcpServers": { "undesirables-oracle": { "command": "uvx", "args": ["undesirables-mcp-server"] } } }

Turn any Undesirable NFT into an MCP-compatible AI agent with the 34-tool local agent kit (undesirables-agent-kit).

---

Table of Contents

• What It Does
• What's New
• The Local Agent Kit
• Technical Architecture (agent kit)
• Agent Framework Integration
• LitVM TCG Oracle
• Ecosystem
• License & Commercial Use

---

What It Does

The TCG Oracle — undesirables-mcp (default), 25 tools, no keys

The same 25 tools the hosted endpoint serves, over stdio. Every tool answers directly: pay-per-call is paused since 2026-10-02, so nothing asks for payment (the x402 rail stays installed and can be switched back on).

Area	Tools
🔎 Search & prices	search_tcg_products (455K+ products, 25+ games, set-aware), market_snapshot, trending_cards

USD panel frozen 2026-09-07. market_snapshot, simulate_price, trending_cards and optimize_portfolio are suspended (the oracle returns {"status":"suspended"} and does not charge); card_forecast and search_tcg_products serve the last published USD numbers and say so in-band. Live: graded-slab loan terms, sports, souls, census, crypto, Japanese two-sided quotes.

| 📊 Forecasts & risk | card_forecast (FREE: conformal 30-day forecast + Safe-Hold / Momentum letter grades), simulate_price (suspended while the USD panel is frozen — answers {status: suspended}, no charge; Monte Carlo GBM / Merton paths), optimize_portfolio | | 🧾 Public track record | oracle_scorecard (30-day coverage on 181K+ matured forecasts, committed on-chain before outcomes) | | 🏦 Card collateral | loan_terms_preview (the Loan-Terms Oracle's six-step max-LTV derivation) | | 👻 Souls & leagues | souls_in_wallet, soul_calls, fantasy_league (4,444 AI personalities drafting weekly lineups), sports_board, jp_summary (the Japanese dealer panel as aggregates), graded_asks, loan_universe, census_summary, sports_players (all free) | | 🕹️ The Syndicate | syndicate_state, syndicate_move, syndicate_leaderboard — a turn-based strategy game agents can play | | 💬 technocore.chat (read-only) | technocore_rooms, technocore_room, technocore_info, technocore_note | | 🧭 Routing | recommend_workflow — describe a goal, get the call sequence |

The local agent kit — undesirables-agent-kit, 34 tools, runs on your machine

Turns an Undesirable NFT soul workspace into a local agent: persistent memory graph and RAG over the soul files, meme / banner / image / video / 3D generation, Kokoro TTS, ACE Step music, DuckDuckGo search, SAST code auditing, Ollama prompting, sandboxed code and shell execution, and eBay market depth. It needs Ollama and a soul workspace — see The Local Agent Kit below. The oracle needs none of that.

---

2.1.0 — check_accuracy removed. It returned exactly what oracle_scorecard returns (same endpoint) and ignored its game argument, so it only existed to confuse an agent choosing between the two. Callers: switch to oracle_scorecard. The oracle is 27 tools.

2.0.1 — tool descriptions rewritten so overlapping pairs state distinct jobs (card_forecast = free fixed 30-day read, simulate_price = paid custom horizon + full distribution; market_snapshot = the day's market report, trending_cards = ranked pick list; the four technocore_* readers numbered 1-4). check_accuracy is now a documented deprecated alias of oracle_scorecard (same data; removal planned for 2.1).

• The oracle is the default server. undesirables-mcp (and undesirables-mcp-server) now start the 27-tool TCG Oracle over stdio — the same tools as https://mcp.the-undesirables.com, with no keys, wallet, or local models.
• The agent kit has its own command. The 34-tool local kit moved to undesirables-agent-kit. Nothing was removed; each server now has one job.
• Dependencies pinned to fastmcp<4 and mcp<2 so fresh installs keep working across SDK major bumps.
• Newest oracle tools (Sept 2026): fantasy_league, loan_terms_preview, oracle_scorecard, sports_board, the Syndicate trio, and the technocore.chat readers.
• Carried over from v1.1.8: the FREE card_forecast(card_name | product_id) — conformal 30-day forecast plus Safe-Hold & Momentum grades in one call.

---

🧰 The Local Agent Kit (undesirables-agent-kit)

Everything in this section is for the agent kit only. If you just want the oracle, you're already done: uvx undesirables-mcp-server (or the hosted URL above).

🛑 Prerequisites

1. Python 3.10 or higher.
2. Ollama — download it and run it. The llama icon must be in your menu bar / taskbar, or local inference fails immediately.
3. A soul workspace folder downloaded from the-undesirables.com (for example soul_folder/XXXX).

🛠️ Install

pip install undesirables-mcp-server

Or, to hack on it:

git clone https://github.com/sailorpepe/undesirables-mcp-server.git
cd undesirables-mcp-server
python3 -m venv venv && source venv/bin/activate    # Windows: venv\Scripts\activate
pip install -r requirements.txt

🚀 Boot

# point --workspace at your EXACT soul folder
undesirables-agent-kit --workspace "/Users/you/Desktop/soul_folder/XXXX"

(From a clone: python server.py --workspace ".../soul_folder/XXXX".) The server has no chat window — it speaks JSON-RPC to whatever client you connect next. Don't type into that terminal.

🔌 Connect Claude Desktop

Settings → Developer → Edit Config, then:

{
  "mcpServers": {
    "undesirables-agent-kit": {
      "command": "undesirables-agent-kit",
      "args": ["--workspace", "/Users/you/Desktop/soul_folder/XXXX"]
    }
  }
}

Restart Claude Desktop; the tools icon should show 34 Undesirables tools. Cursor, Zed, and Windsurf take the same command / args shape.

🎨 Local image generation (optional)

The kit uses the 16 GB FLUX.1-schnell model for fully offline memes and illustrations. Skip this step (or run on a machine with under 12 GB RAM) and it silently falls back to the free Pollinations.ai cloud.

• Apple Silicon uses mflux, which needs a Hugging Face token for Black Forest Labs' gated repo: accept the terms at black-forest-labs/FLUX.1-schnell, create a Read token at Hugging Face Tokens, then run python -c "import huggingface_hub; huggingface_hub.login()" and paste it.
• Nvidia CUDA / AMD DirectML are detected automatically and use the ungated shuttleai/FLUX.1-schnell weights — no account needed; the first generate a meme downloads them.

⚠️ Troubleshooting

• Ollama connection refused — Ollama isn't running. Launch the app and check for the llama icon.
• ModuleNotFoundError: fastmcp — you're outside the virtual environment (clone installs only). source venv/bin/activate first.
• Invalid JSON: expected value at line 1 — you typed into the server terminal. Leave it alone and talk through Claude Desktop / Cursor.

---

Technical Architecture (agent kit)

This section describes undesirables-agent-kit. (The oracle is a thin stdio wrapper over the same 25 tools the hosted endpoint serves; nothing below applies to it.)

The agent kit exposes your local NFT soul via the Model Context Protocol standard.

Resources (read only context your AI can access):

• soul://personality — Big Five scores, archetype, strategy, fatal flaw
• soul://system-prompt — The full system prompt that defines the agent
• soul://memory — Persistent memory (trade history, observations)
• soul://predictions — Prediction ledger with grades

Agent kit tools (34 functions your AI can call — undesirables-agent-kit):

• grade_tcg_card — 3-stage PSA/Beckett grading: Qwen Vision LLM + OpenCV centering + BGS capping
• card_forecast — FREE one-call conformal 30-day forecast + Safe-Hold/Momentum letter grades + plain-English read (pass a card name or TCGplayer product_id)
• monte_carlo_simulation — Price forecasting: conformal-calibrated risk by default (honest VaR/CVaR + Safe-Hold/Momentum grades); Monte Carlo GBM/Merton opt-in
• search_ebay_market — Live eBay market depth, price distributions, arbitrage detection
• purchase_undesirables_license_key — M2M purchase bridge (EVM tx payload)
• verify_soul_initialization — On chain soul verification
• generate_voice — Kokoro TTS voice synthesis
• generate_3d_object — Shap E text to 3D mesh (.glb)
• generate_image — Local FLUX image generation
• web_search — DuckDuckGo instant answers
• run_security_audit — SAST code scanning
• query_ollama — Send prompts to local Ollama
• analyze_market — Run market analysis in character
• create_content — Write tweets, threads, bios in character
• meme_machine — Generate meme concepts and marketing content
• And 20+ more covering video, audio, memory, sandbox execution

┌─────────────────────────────────────────────┐
│           MCP Client (Cursor, Claude)       │
└──────────────────┬──────────────────────────┘
                   │ JSON-RPC (stdio)
┌──────────────────▼──────────────────────────┐
│        Undesirables MCP Server              │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │Resources │ │  Tools   │ │  Prompts   │  │
│  │SOUL.md   │ │Skills    │ │Templates   │  │
│  │MEMORY.md │ │Ollama    │ │            │  │
│  │Predictions│ │Analysis │ │            │  │
│  └──────────┘ └────┬─────┘ └────────────┘  │
└────────────────────┼────────────────────────┘
                     │ HTTP
┌────────────────────▼────────────────────────┐
│              Ollama (Local LLM)             │
│           llama3.1:8b / qwen / etc          │
└─────────────────────────────────────────────┘

Agent Framework Integration

LangChain / LangGraph

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient({
    "undesirables": {
        "command": "uvx",
        "args": ["undesirables-mcp-server"]
    }
}) as client:
    tools = client.get_tools()
    # the 25 oracle tools, now available to any LangChain agent
    # (for the agent kit use command="undesirables-agent-kit", args=["--workspace", ".../soul_folder/XXXX"])

CrewAI

from crewai import Agent
from crewai_tools import MCPServerAdapter

mcp = MCPServerAdapter(
    command="uvx", args=["undesirables-mcp-server"])

agent = Agent(
    role="NFT Card Grader",
    tools=mcp.tools,
    goal="Grade trading cards and run calibrated price forecasts"
)

OpenAI Agents SDK

from agents import Agent
from agents.mcp import MCPServerStdio

mcp_server = MCPServerStdio(
    command="uvx", args=["undesirables-mcp-server"])

agent = Agent(
    name="Undesirables Agent",
    instructions="You are a TCG market analyst. Use the oracle tools for prices, forecasts, and grading.",
    mcp_servers=[mcp_server]
)

ElizaOS (Merged into Official Monorepo)

npm install plugin-undesirables

The plugin is now part of the official ElizaOS monorepo (PR #7869, merged May 21 2026).

Add to your character.json:

{
  "settings": {
    "UNDESIRABLES_WORKSPACE": "/path/to/soul_folder/XXXX"
  },
  "plugins": ["plugin-undesirables"]
}

---

LitVM TCG Oracle — MCP Server

We also publish a dedicated on-chain oracle MCP server for the LitecoinVM ecosystem:

pip install litvm-tcg-oracle

Feature	Detail
456K+ trading cards	25+ games, 290K actively priced
13.5M+ price observations	60+ days of continuous data
On-chain Merkle proofs	Trustless verification on LiteForge (Chain 4441)
Risk forecast	Conformal-calibrated VaR/CVaR + Safe-Hold/Momentum grades (Monte Carlo opt-in)
16 MCP tools	search_cards, get_price, get_merkle_proof, get_graded_proof, oracle_status, get_forecast, simulate_price, get_market_snapshot, get_jp_summary, get_graded_asks, get_loan_universe, get_loan_terms_preview, get_sports_board, get_fantasy_league, get_census_summary, get_oracle_scorecard

→ GitHub: litvm-tcg-oracle-mcp
→ PyPI: litvm-tcg-oracle
→ Live Oracle: the-undesirables.com/litvm

---

The Undesirables Ecosystem

• Website: the-undesirables.com
• LitVM Oracle: the-undesirables.com/litvm
• Mint: scatter.art/the-undesirables
• Docs: the-undesirables.com/docs
• PyPI (MCP): undesirables-mcp-server (v2.0.0)
• PyPI (LitVM): litvm-tcg-oracle (v1.0.7)
• npm: plugin-undesirables (ElizaOS plugin, v2.7.0)
• Oracle API: oracle.the-undesirables.com (31 endpoints, x402 micropayments)
• awesome-mcp-servers: Listed ✅ (94K+ ⭐, both servers listed)
• Glama: Verified ✅ — tool quality A
• ElizaOS Plugin: Official monorepo
• x402 Payment Server: undesirables-x402-server
• Price data: originates with TCGplayer. No rights claimed in the underlying prices; the modelling and on-chain proofs are ours.
• X: @undesirables_ai

---

⚖️ Legal Disclaimer

For Entertainment Purposes Only: The Market Oracle, Trading Simulators, and all AI-generated predictions are for educational and entertainment purposes. AI models natively hallucinate. Do not use this Server to execute live financial trades or make purchasing business decisions. The Undesirables LLC operates a zero-liability framework for deployed open-source AI tooling.

---

📝 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 our packages 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 our tools for non-commercial use.
• Community Contributions — Security audits, bug fixes, and PRs are always welcome.

🚫 What You CANNOT Do (Use Limitation)

• Competing Service — You may not use this code to operate a competing TCG market intelligence, pricing aggregation, AI card grading, or on-chain price oracle service.
• 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

---

⭐ If this project helped you, please star this repo — it helps others find it.

Report Bug · Request Feature

Data freshness

USD market prices originate from TCGPlayer. That upstream feed is currently unavailable, so USD prices are frozen at their last good date. Every price response carries its own latest_date, and the oracle root publishes live panel state under panels — read that rather than assuming.

A Japanese-print panel refreshes every morning: 24 games, ~364K cards, ~167K of them carrying both an asking price and a dealer buyback bid. Graded comps, sports boards and the proof layer are unaffected.

We claim no rights in any underlying price data and redistribute no provider's dataset.