Pulltrader MCP server
Commit Oct 4, 2026Identify trading cards, analyze market value through recent sales, and calculate net proceeds across various marketplaces.
Also known as pulltrader/pulltrader-mcp, pulltrader-mcp
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- 0.6.1
- Last commit
- Oct 4, 2026
- License
- MIT
What is Pulltrader MCP?
Pulltrader is an MCP server. Identify trading cards, analyze market value through recent sales, and calculate net proceeds across various marketplaces. It exposes 17 tools, such as identify_card, search_card_sales, summarize_card_market.
Summary generated from the project's README
About Pulltrader MCP server
Trading-card collectors and dealers can research market values and calculate potential profits directly through their AI assistant. This read-only server provides tools to resolve natural language descriptions into structured card data, retrieve recent comparable sales, and view price history charts. It is designed for users of Claude, ChatGPT, and Cursor who need quick access to trading card economics without switching applications.
The server includes a deterministic engine to estimate seller proceeds across various marketplaces like eBay and Pulltrader. It calculates net profit by accounting for specific fee schedules, shipping amounts, and seller plans. Users can also determine the exact sale price required to reach a specific target take-home amount. Beyond market research, the system includes a Kapture tool to check if a card certificate matches a stolen-card registry.
Setup requires connecting to a remote HTTP endpoint. The service is public and does not require authentication, though it enforces rate limits to manage data usage. All market figures are estimates based on recent sales, and all financial calculations are performed by the server to ensure accuracy rather than relying on model inference.
What you can do with it
- 1Identify specific trading cardsConvert a text description of a card into structured data including player, set, and grade.
- 2Analyze market value trendsView recent comparable sales and price history charts to understand a card's value.
- 3Compare marketplace profitabilityCalculate how much money you will actually keep when selling a card on different platforms.
- 4Calculate target sale pricesFind the necessary listing price to ensure you hit a specific net profit goal after fees.
- 5Verify card authenticityCheck a certification number against a registry to see if the card has been reported stolen.
Written from the project's README. Every use case is checked against a quote from it.
How to install Pulltrader MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Pulltrader MCP in Claude Code
$ claude mcp add --transport http pulltrader-mcp https://mcp.pulltrader.app/mcpInstall Pulltrader MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"pulltrader-mcp": {
"url": "https://mcp.pulltrader.app/mcp"
}
}
}Install Pulltrader MCP in VS Code
.vscode/mcp.json
{
"servers": {
"pulltrader-mcp": {
"type": "http",
"url": "https://mcp.pulltrader.app/mcp"
}
}
}Install Pulltrader MCP in VS Code CLI
$ code --add-mcp '{"name":"pulltrader-mcp","type":"http","url":"https://mcp.pulltrader.app/mcp"}'Install Pulltrader MCP in Codex
$ codex mcp add pulltrader-mcp --url https://mcp.pulltrader.app/mcpInstall Pulltrader MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.pulltrader-mcp] url = "https://mcp.pulltrader.app/mcp"
Install Pulltrader MCP in Gemini CLI
$ gemini mcp add -s user --transport http pulltrader-mcp https://mcp.pulltrader.app/mcpInstall Pulltrader MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"pulltrader-mcp": {
"url": "https://mcp.pulltrader.app/mcp",
"type": "http"
}
}
}Pulltrader MCP tools 17
Detected from the READMEidentify_cardsearch_card_salessummarize_card_marketget_card_price_historycompare_selling_costscalculate_required_sale_priceexplain_selling_methodcurrencyquantityshipping_amountitem_categoryseller_plan
| identify_card | — | |
| search_card_sales | — | |
| summarize_card_market | — | |
| get_card_price_history | — | |
| compare_selling_costs | — | |
| calculate_required_sale_price | — | |
| explain_selling_method | — | |
| currency | — | |
| quantity | — | |
| shipping_amount | — | |
| item_category | — | |
| seller_plan | — |
Show all 17 toolsShow fewer tools
seller_levelseller_covers_feesebay_store_subscriptionacquisition_costebay_fee_percent_override
| seller_level | — | |
| seller_covers_fees | — | |
| ebay_store_subscription | — | |
| acquisition_cost | — | |
| ebay_fee_percent_override | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepulltrader/pulltrader-mcp is public and reachablegithub.com/pulltrader/pulltrader-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-04github.com/pulltrader/pulltrader-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubPulltrader — Trading-Card MCP Server
Identify a card, pull recent sold comps, summarize its market value, chart its price history, and compare what a seller keeps across eBay, Pulltrader, and other card marketplaces — inside your AI assistant.
A public, read-only Model Context Protocol server for trading-card research and selling. Eight tools: a Kapture stolen-card registry check, four back onto Pulltrader's card data (identification, comparable sold sales, market value, price history), three run Pulltrader's deterministic seller-economics engine over a dated, versioned fee schedule.
Market figures are estimates derived from recent sales. Fee math is deterministic — the server computes it and never asks the model to infer fees from prose. eBay figures are clearly labeled estimates.
- Transport: Streamable HTTP (
POST /mcp) - Auth: none (public, read-only)
- Endpoint:
https://mcp.pulltrader.app/mcp - Registry name:
app.pulltrader/seller-economics - Protocol:
2025-06-18(the client's requested version is echoed when present)
Who it's for
Trading-card sellers, dealers, shops, and collectors who want to know what a card is, what it's worth, and what they'd actually take home selling it — without leaving their assistant.
What it does (and doesn't)
| Does | Doesn't |
|---|---|
| Resolve a prose card description into structured fields | Identify a card from an image (text only) |
| Return recent comparable sold sales (price + date) | Return listing, affiliate, or per-sale outbound URLs |
| Summarize market value: median, mean, p10–p90, volatility, confidence | Claim a guaranteed value or give financial advice |
| Chart price history by day / week / month with a trend | Make any write, order, or account change |
| Estimate seller fees and net proceeds per selling method | Claim one platform is universally cheapest |
| Solve for the price needed to hit a target net | Model auction formats (hammer, buyer's premium, consignment) |
| State its assumptions, data freshness, and limitations | Cover non-card categories or currencies other than USD |
Tools
Kapture cert check (data-backed)
check_kapture_cert accepts { "cert": "00123456" } and preserves leading zeros.
CLEAN only means no verified stolen report matched. STOLEN includes the Kapture
report and a voluntary Pulltrader recovery-form link. The tool never collects
personal information, infers possession, or submits a recovery report. The backend
holds KAPTURE_API_KEY; no new Worker secret is needed. Recovery handoff is manual
until Kapture provides a reporting API. See pulltrader-backend/docs/KAPTURE.md.
Card research (data-backed)
These bridge to the Pulltrader backend. Card data is limited-public: a capped sample of sales, no per-listing or affiliate URLs, and only the catalog reference image.
Each accepts either query (a natural-language description, e.g. "2023 Panini Prizm Victor Wembanyama #136 Silver PSA 10") or item (structured fields: player_athlete, year_manufactured, set_name, card_number, parallel_variety, grader, grade, sport). One of the two is required.
| Tool | What it returns |
|---|---|
identify_card |
Canonical fields (player/athlete, year, set, number, parallel, grader, grade, category) plus a confidence level and which fields resolved. Takes query only. Does not price the card. |
search_card_sales |
A capped sample of recent comparable sold sales (price + date) plus a market snapshot. Optional limit. |
summarize_card_market |
Canonical market value: median, mean, p10–p90, volatility, sample size, confidence. |
get_card_price_history |
A chart-ready time series with a trend. Optional interval: day | week | month. |
When eBay has no dated comps, search_card_sales and summarize_card_market fall back to the authoritative vendor price and surface market_value, value_source (TCG Market | CardSightAI | eBay Comps), price_change_7d, price_change_30d, and a single catalog image.
Seller economics (deterministic, no I/O)
| Tool | What it returns |
|---|---|
compare_selling_costs |
Estimated fees and net proceeds for one sale across selling methods, with a per-method fee breakdown, the difference vs the eBay baseline, and the assumptions used. Requires sale_price. |
calculate_required_sale_price |
The per-item price needed to reach a target take-home (or net profit, when acquisition_cost is given) on a single method. Requires target_net. |
explain_selling_method |
Plain, structured explanation of how each method owns the listing, fulfills, and charges fees. Derived from the same engine, so it never drifts from compare_selling_costs. |
Shared inputs (compare_selling_costs, calculate_required_sale_price):
| Field | Type | Default | Notes |
|---|---|---|---|
currency |
enum USD |
USD |
Only USD supported |
quantity |
integer | 1 |
Per-order fixed fees applied once |
shipping_amount |
number | 0 |
Affects eBay's fee base |
item_category |
enum trading_cards |
trading_cards |
Only trading cards |
seller_plan |
free|starter|pro|shop |
free |
Marketplace payout tier |
seller_level |
enum | derived from plan | Explicit payout level override |
seller_covers_fees |
boolean | false |
If false, the buyer pays the platform fee |
ebay_store_subscription |
boolean | false |
eBay Store rate (12.35%) vs individual (13.25%) |
acquisition_cost |
number | — | Switches output to net profit |
ebay_fee_percent_override |
number | — | Override the estimated eBay FVF % (flat) |
Supported methods: ebay, pulltrader_marketplace, pulltrader_fbp, pulltrader_storefront, pulltrader_pos, plus estimated competitor marketplaces tcgplayer, manapool, misprint, fanatics_collect, goldin (off by default — opt in via methods). Competitor figures model fixed-price / Buy Now seller fees only.
Example prompts
- "What is this card: 2023 Bowman Chrome Elly De La Cruz PSA 10?"
- "Show me recent sold comps and the market value for that card."
- "What's the price history on a 2018 Prizm Luka Doncic Silver PSA 10 over the last year?"
- "Compare my estimated proceeds on a $250 graded-card sale."
- "What would I keep on an $80 card on eBay vs Pulltrader?"
- "What do I have to sell it for to clear $200 after fees?"
- "Explain the assumptions behind this payout estimate."
Example response (text summary)
On a $250.00 trading-card sale, estimated seller proceeds by method:
- Sell it yourself on eBay: keep $216.47 (estimated) (fees $33.53, 13.41%)
- Pulltrader marketplace (you ship): keep $235.00 (fees $15.00, 6%)
- Your Pulltrader storefront (you ship): keep $250.00 (fees $0.00, 0%)
For these inputs, Your Pulltrader storefront (you ship) returns about $33.53 more than Sell it yourself on eBay.
Estimate based on fee schedules updated 2026-06-01 (Pulltrader) and 2026-06-27 (eBay, estimated). Estimates only, for trading cards in USD. ...
eBay = 13.25% individual FVF + $0.40 per-order fee (orders over $10). The storefront keeps 100% because Pulltrader has no seller fee on storefront/POS — only the platform fee, paid by the buyer here. The platform fee is always charged on Pulltrader card sales (buyer pays by default).
Connecting
Claude (web / Desktop)
Settings → Connectors → Add custom connector → URL https://mcp.pulltrader.app/mcp.
ChatGPT
Settings → Apps & Connectors → Advanced → enable Developer mode → Create → URL https://mcp.pulltrader.app/mcp.
Cursor / generic
Add to your MCP client config:
{
"mcpServers": {
"scout-by-pulltrader": {
"url": "https://mcp.pulltrader.app/mcp"
}
}
}
Tested clients: Claude (web/Desktop), ChatGPT developer mode, Cursor, MCP Inspector. We do not claim universal compatibility with every assistant.
Public access & rate limits
The /mcp endpoint is public and read-only. A separate seller resource is implemented at /seller/mcp; OAuth is provisioned and its signed-in pilot is pending. See Seller MCP.
| Limit | Default | Notes |
|---|---|---|
All POST /mcp |
60 / IP / min | HTTP 429 + Retry-After. Fail-open if KV is down. |
| Data tools (identify / comps / market / history) | 8 / IP / min, 40 / IP / day | Tool isError RATE_LIMITED. Fail-closed if KV is down. |
| Data tools global | 10,000 / day | Circuit breaker for model + comps spend. |
| Batch size | 5 messages | Larger batches are rejected. |
Requires the MCP_ABUSE KV namespace (see wrangler.toml). Tune via PUBLIC_RATE_LIMIT_PER_MIN, DATA_RATE_LIMIT_PER_MIN, DATA_RATE_LIMIT_PER_DAY, DATA_GLOBAL_LIMIT_PER_DAY.
Errors
Input problems come back as a tool result with isError: true and a stable code, not a JSON-RPC error: INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, UPSTREAM_TIMEOUT, DATA_BACKEND_UNAVAILABLE, INTERNAL_ERROR. Unknown methods and malformed envelopes use standard JSON-RPC error codes.
The four card tools require the backend bridge (PULLTRADER_API_BASE + SCOUT_MCP_SECRET). Without it they degrade to DATA_BACKEND_UNAVAILABLE; the three seller-economics tools are pure and always available.
Data sources & fee freshness
- Card data is limited-public and estimate-only: a capped sample of recent sold comps, aggregated by the shared Pulltrader domain engine.
- Pulltrader fees mirror Pulltrader's authoritative internal fee configuration.
- eBay fees are an estimate of published trading-card rates (tiered individual/Store final value fee + order-size-based per-order fee), updated and reviewed on a schedule. See docs/FEE_SCHEDULES.md. Responses warn if a schedule is past its review date.
Current schedule versions are served live at /version.
Limitations
- eBay estimates exclude promoted listings, international fees, buyer-paid sales tax, and the seller's own shipping-label cost.
- Market values are estimates from recent sales, excluding fees, taxes, and shipping.
- Not financial advice; actual proceeds and actual value vary.
- Trading cards / USD only in this release.
Development
npm install
npm run typecheck # tsc --noEmit
npm test # vitest
npm run dev # wrangler dev (local)
Deploy and registry submission require explicit approval — see docs/DEPLOYMENT.md and docs/DISTRIBUTION.md. Do not deploy or publish from a development session.
More
Deploy prerequisites
wrangler kv namespace create MCP_ABUSE
wrangler kv namespace create MCP_ABUSE --preview
# Paste ids into wrangler.toml [[kv_namespaces]] binding MCP_ABUSE
wrangler secret put SCOUT_MCP_SECRET
Roadmap
- Image-based card identification.
- Athlete/player profile tools.
- Complete the signed-in seller pilot for
/seller/mcp; global per-user quotas remain future work.
Built and maintained by Pulltrader. Support: support@pulltrader.app
This repository is the public mirror of the Pulltrader MCP Worker, exported from the Pulltrader monorepo on each release. Issues and questions are welcome here; pull requests are applied upstream. wrangler.toml KV ids are redacted — deploys run from the monorepo.
Pulltrader MCP questions
How do I add Pulltrader MCP to Claude Code?
Run claude mcp add --transport http pulltrader-mcp https://mcp.pulltrader.app/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Pulltrader MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Pulltrader MCP provide?
It exposes 17 tools, including identify_card, search_card_sales, summarize_card_market, get_card_price_history, compare_selling_costs.
Can I identify a card using an image?
No, the current version only supports identifying cards via text-based prose descriptions or structured fields.
Does the server provide financial advice?
No, the market figures provided are estimates and the tool does not claim to give financial advice.
What currencies are supported?
The server currently only supports USD.
How are the seller fees calculated?
The server uses a deterministic engine to compute fees rather than asking the model to infer them from text.