# mrmarket.ai MCP server

Analytical engine for US-listed equities: screens, rankings, and event studies in plain English.

## Links
- Registry page: https://www.getdrio.com/mcp/ai-mrmarket-mrmarket-mcp
- Repository: https://github.com/codinghaven/mrmarket-mcp
- Website: https://mrmarket.ai

## Install
- Endpoint: https://mcp.mrmarket.ai/mcp
- Auth: Not captured

## Setup notes
- Remote endpoint: https://mcp.mrmarket.ai/mcp

## Tools
- getting_started - Onboarding tour for mrmarket.ai — call this FIRST in a fresh session, or any time the user
asks "what can you do?" / "how does this work?". Zero LLM cost, zero credits, returns a
structured orientation packet (tools, capabilities, limits, examples, troubleshooting, help).

Default scope ('overview') covers everything in a short tour. Optional `topic` deep-dives a
single area without re-fetching the whole thing:
  - tools        → tool-by-tool reference for query_data, describe_data, get_symbols,
                   get_account_status, report_issue.
  - examples     → 20+ verified working prompts grouped by use case (screens, rankings,
                   comparisons, cohort-relative, time-series, event-vs-price).
  - limits       → universe, freshness, what is NOT supported (intraday, options, news,
                   backtests in one call).
  - cost         → credit model, which tools are free, how to read `credits_remaining`.
  - troubleshoot → error_code → recipe (RATE_LIMITED, INSUFFICIENT_CREDITS, QUERY_NOT_UNDERSTOOD,
                   empty result, wrong-looking answer).
  - help         → links + how to reach support; preferred channel is `report_issue`.

Use it to bootstrap your understanding of the server before asking real questions —
that's the fastest path to a useful first answer for the user. Endpoint: https://mcp.mrmarket.ai/mcp
- query_data - YOU ARE a research assistant helping a retail investor get answers from mrmarket.ai.
You are NOT a database engineer. Ask questions the way a financial analyst would say
them out loud — plain English, focused on intent. The server has a domain-trained
financial expert that translates your question into the right methodology, picks
appropriate thresholds, and documents every interpretation in the response so the
user can see and correct what was assumed.

Answers analytical financial questions about US-listed equities in a single call.
Send the full natural-language question — not SQL. Returns structured rows + columns.

CAPABILITIES — all handled in one call:
  - Top-N / bottom-N rankings by any metric
  - Multi-criteria stock screens (combine sector, ratios, growth thresholds, insider activity)
  - Computed financial metrics: ROIC, FCF, D/E, margins, ROE, ROA, dividend yield, growth rates
  - Period-over-period changes: QoQ, YoY, multi-year
  - Rolling averages, trend slopes, volatility, correlation, statistical measures
  - Multi-symbol comparisons and time-series trends
  - Sector/industry rollups and averages
  - Cohort-relative analysis (vs sector average, vs universe z-score)
  - Forward returns after events (earnings beats, insider buys)
  - Price charts with event overlays (earnings dates, insider transactions)
  - Consecutive-quarter screening (e.g., 4 quarters of growing FCF)

EXAMPLES — notice how these read like a human asking, not a technical specification:
  - "Top 20 stocks by ROIC excluding financials"
  - "Companies with 4 consecutive quarters of growing free cash flow"
  - "Compare AAPL, MSFT, and GOOGL revenue over the last 5 years"
  - "Stocks whose ROIC is at least 1 standard deviation above their sector average"
  - "Average 30-day stock return after companies beat earnings by more than 10%"
  - "AAPL daily closes for the last 5 years with earnings dates overlaid"
  - "Top 20 quality compounders by 5-yr ROIC stability and margin trend"
  - "Find undervalued stocks with recent insider buying — low P/E, strong FCF, low debt"
  - "Average stock return 90 days after large CEO insider purchases"

HOW TO PHRASE YOUR QUESTION — this matters for best results:

Pass the user's question through with minimal rewording. The server's financial
expert interprets casual language better than you can translate it:
  - "large purchase" → appropriate dollar threshold (documented in assumptions[])
  - "90 days" → trading-day equivalent (documented in assumptions[])
  - "CEO" → executive title matching
  - "growing" → positive AND increasing
  - "cheap" / "undervalued" → appropriate valuation thresholds
  - "Buffett screen" / "quality compounder" → recognized analytical frameworks

DO:
  ✓ Preserve the user's intent and language faithfully
  ✓ Use directional terms: "low P/E", "strong cash flow", "high margins"
  ✓ Add thresholds ONLY when the user stated them explicitly
  ✓ Ask for aggregated answers when the user wants a summary ("average return after...")
  ✓ Combine multi-criteria screens into ONE question, not separate calls

DON'T:
  ✗ Invent numeric thresholds the user didn't specify — the server picks sensible
    defaults and surfaces them in assumptions[] so the user can adjust
  ✗ Specify column lists — the server selects the most relevant columns automatically
  ✗ Convert calendar days to trading days — the server handles this
  ✗ Add metrics or time ranges the user didn't request — adds complexity and risk
  ✗ Use AND/OR boolean syntax — plain English works better
  ✗ Prefix with jargon like "Event study:" or "Screen:" — just ask the question

GOOD: "Find undervalued stocks with recent insider buying — low P/E, strong FCF, low debt"
BAD:  "Screen for companies where insiders have made open-market stock purchases in the
       past 3 months AND P/E ratio below 20 AND price-to-book below 3 AND positive free
       cash flow AND debt-to-equity below 1. Show symbol, name, sector, P/E..."

GOOD: "Average stock return 90 days after large CEO insider purchases"
BAD:  "For all insider buy transactions where title contains 'CEO' or 'Chief Executive'
       and transaction value > $100,000, calculate the return 63 trading days after..."

Both versions will work, but the GOOD versions produce better results: the server's
financial expert picks market-appropriate thresholds and documents them in assumptions[]
so the user can see and correct them. Your pre-translations hide these from the user.

DO NOT split these into multiple calls — they all work in one:
  - Multi-symbol comparison ("monthly returns for TSLA and SPY" — not two separate calls)
  - Multi-metric screens ("high ROIC, strong margins, low debt, consistent earnings")
  - Cross-metric formulas ("stocks where margin > 2x sector average")
  - Forward return studies ("average return after big earnings beats")
  - Cohort relatives ("ROIC ≥ 1 stddev above sector mean")
  - Price + overlay charts ("price chart with earnings markers")
  - Sector rollups ("average ROIC by sector, ranked")
  - MULTIPLE RETURN HORIZONS IN ONE CALL — this is critical. "Returns at 1, 5, 10, 21,
    and 63 days after earnings" is ONE call, not five. The server computes all forward
    windows in parallel. Never split by horizon — it scans the same data N times for
    no benefit. Even 5+ horizons in one call is fine.
  - Multi-entity data retrieval — "show ROIC, FCF yield, D/E, 6-month return, and
    earnings beat rate for every stock" is ONE call even though it touches fundamentals,
    prices, and earnings. The server joins them internally. Don't confuse "can't compute
    a composite score in SQL" with "can't fetch all the data in one call." Fetch in one
    call, score/rank/normalize in code.
  - Simple classifications — "stocks drawn down 25%, classify as earnings-driven or
    multiple-compression" is ONE call. The server handles conditional labels on joined
    data. Only split when you need the output of one call to parameterize the next.

COMPUTE IN CODE WHEN YOU CAN. Each query_data call costs credits and can fail. If you
already have data from a previous call, compute locally instead of calling again:
  - Aggregations (averages, sums, medians, min/max)
  - Percentage changes, ratios, growth rates
  - Sorting, filtering, grouping, ranking
  - Statistical measures (std dev, correlation, z-scores)
  - Percentile normalization, composite scoring, factor weighting
  - Pairwise correlations, covariance matrices
Only call query_data when you need NEW data you don't already have.

KNOWN LIMITATIONS — disclose to the user, don't silently work around:
  - MEDIAN is not supported as an aggregation. If the user asks for median, say so and
    offer average + standard deviation as an alternative. Don't silently substitute.
  - Max drawdown requires a continuous equity curve — per-trade returns only approximate
    it. Disclose the approximation.

DECOMPOSE INTO MULTIPLE CALLS only when:
  (a) Iteration with state — backtests with rebalancing, compounded returns
  (b) Randomness — Monte Carlo, bootstrap simulations
  (c) Optimization — portfolio weights, factor blending, risk parity
  (d) Custom multi-factor scoring with user-supplied weights — fetch all metrics in ONE
      call, do the scoring/weighting in code
  (e) Genuinely unrelated reports with no shared universe
  (f) "Full analysis" of a single stock — split by: (1) valuation vs sector,
      (2) financial trends (revenue, margins, FCF, EPS), (3) insider activity.
      Always announce the plan first.
  (g) Screen-then-drill — when you need to screen first, then fetch historical data
      for qualifying symbols (you don't know the symbols until the screen returns)

If the response carries `meta.needs_decomposition: true`, retry as parallel calls
using `meta.suggested_split`.

ANNOUNCE YOUR PLAN FOR 2+ CALLS on vague requests ("full analysis", "comprehensive
overview"). For specific multi-part questions, announce at 3+ calls. Tell the user
in plain language with rough credit cost before proceeding.

OUTPUT SIZE: the MCP tool-result ceiling is ~1MB. Quick math:
  - 1 month ≈ 21 trading days, 1 year ≈ 252
  - Practical ceilings: ~5,000 price rows or ~2,500 fundamental rows
  - PREFER narrowing/summarizing first ("per-stock 6mo return" not "all stocks 6mo daily prices",
    or narrow by sector/time range). A focused question is almost always the better answer.
  - If a result is still too large, the server no longer fails — it returns page 1 plus a
    full-dataset `summary` and a free `pagination.next_cursor`. Call `fetch_page` with that
    cursor ONLY when the user genuinely needs every raw row; a summary/ranking is usually enough.
    For very large dumps, hand the user `view_url` (the full dataset) instead of paginating.

OUT OF SCOPE: intraday/tick data, options chains, news/transcripts, macroeconomic series,
portfolio simulation, optimization.

RESPONSE FORMAT — what to expect back:
  - `data`: array of row objects keyed by column name (e.g., [{symbol: "AAPL", revenue: 394328000000}, ...])
  - `columns`: metadata for each column — `name`, `type` (currency/percent/number/string/date/boolean),
    `displayName` (human-friendly label). Use `type` to format values for the user:
    currency → "$394.3B", percent → "18.5%", date → "2024-09-30"
  - `row_count`: total rows returned
  - `assumptions`: what the server assumed on the user's behalf (thresholds, time ranges,
    metric interpretations). ALWAYS surface these to the user so they can correct them.
  - `warnings`: diagnostic notes (low credit balance, applied defaults)
  - `credits_remaining` / `cost_credits`: balance after this call / what this call cost
  - `truncated` + `pagination` (oversize results only): `truncated: true` means this is page 1
    of a larger result. `pagination` has `page_index`, `page_count`, `has_more`, `total_rows`,
    and `next_cursor` — pass next_cursor to `fetch_page` (FREE) for the next page. `summary` is a
    full-dataset per-column digest (min/max/mean/nulls) so you can often answer without paging.

On error: `error_code` + `message` + `retryable` flag. Retry once if retryable is true.

CLARIFICATION HANDLING: when the question is ambiguous, the server resolves it automatically.
If your client supports MCP elicitation, the user is prompted directly. Otherwise the server
applies a sensible default and proceeds. Either way you get a final answer in one call.
Check `assumptions[]` — always tell the user what was assumed.

LIMITS: 60-second timeout (180s with a clarification roundtrip). No default row cap.
Use `describe_data` to confirm fields exist before composing complex questions. Endpoint: https://mcp.mrmarket.ai/mcp
- fetch_page - Fetch the NEXT page of a large query_data result — FREE (zero credits, runs no
new query). Only use this when a prior query_data (or fetch_page) response had
`truncated: true` and a `pagination.next_cursor`.

When to call: the user genuinely needs MORE of the raw rows than page 1 returned.
If a summary, ranking, or the first rows already answer the question — or you only
needed an aggregate (the response carries a full-dataset `summary` on page 1) —
you are DONE; do NOT paginate.

Pass the cursor string from `pagination.next_cursor` VERBATIM — do not edit or
truncate it. Keep calling fetch_page with each new `next_cursor` until it is null.
Snapshots live ~15 minutes; if the cursor has expired, re-run the original question. Endpoint: https://mcp.mrmarket.ai/mcp
- describe_data - Data catalog — zero cost. Use BEFORE query_data when you're unsure what data is available
or whether a specific field or metric is supported.

Scopes:
  - overview          → list all data categories (prices, financials, earnings, insider
                        transactions, etc.) + key fields + computed metrics. Good first call.
  - category          → full field list for one data category. Pass entity with the category
                        name: 'Stock Prices', 'Income Statements', 'Earnings', etc.
  - computed_metrics  → list of pre-defined computed metrics (ROIC, FCF, D/E, ROE, ROA,
                        margins, EPS/revenue growth, stock return, surprise).
  - search            → keyword search across field names, categories, and computed metrics.
                        Pass search_term: 'volatility', 'dividend', 'capex', etc. Endpoint: https://mcp.mrmarket.ai/mcp
- get_symbols - Fast company/sector/industry lookup. Sub-50ms, zero LLM cost.
Use to resolve names → tickers, list sector members, or get the full universe before
fanning out query_data calls (e.g., for backtests or per-symbol price pulls).
Actions: search | list_sectors | list_industries | by_sector | by_industry | all. Endpoint: https://mcp.mrmarket.ai/mcp
- get_account_status - Account snapshot — zero LLM cost, no credits charged. Returns which mrmarket.ai
account this MCP connection is authorized as (email), the plan tier, the current
credit balance (and subscription vs top-up split), and per-tier query limits.

Use this to (a) confirm the expected account is connected — a mismatch here explains
an unexpected "out of credits", and (b) check the credit balance before running a
batch of queries. Endpoint: https://mcp.mrmarket.ai/mcp
- recent_queries - List the user's most recent `query_data` calls (newest first). Zero LLM cost, zero credits.

Use this when the user references "that query I ran earlier" / "the AAPL one from before" /
"the slow one" — instead of asking the user to dictate the query_id, look it up here. Each
entry returns:
  - query_id      (the mcp_<ts>_<n> handle — pass directly to report_issue or quote to support)
  - status        (success | clarification | timeout | error)
  - error_code    (null on success; the stable error taxonomy otherwise)
  - row_count     (rows returned on success)
  - prompt_preview (first 120 chars of the original question)
  - when          (relative — "2m ago" / "1h ago" / "3d ago")
  - created_at_iso (raw ISO timestamp for precise ordering)
  - execution_time_ms

`limit` defaults to 10, max 50. `status` filters: "all" (default), "success", or "error"
(includes timeouts). Endpoint: https://mcp.mrmarket.ai/mcp
- report_issue - Tell support something went wrong, file a bug, request a feature, or flag a slow query.
Zero LLM cost, zero credits.

Call this when:
  - A `query_data` result looks wrong or misleading (pass the `query_id` from that response —
    support uses it to investigate the issue).
  - You hit a confusing error or the same query keeps failing.
  - A query took unreasonably long (still pass `query_id` if available).
  - You wish mrmarket.ai supported something it currently doesn't.

This is the PREFERRED support channel because it auto-links to the query trace; email is
slower and requires the user to copy/paste the query_id manually.

Categories:
  - wrong_data      → result was incorrect / numbers look off
  - bug             → something crashed or the response was malformed
  - slow            → query took too long or timed out
  - feature_request → "I wish it could do X"
  - general         → catch-all if none of the above fits Endpoint: https://mcp.mrmarket.ai/mcp

## Resources
- mrmarket://data-catalog
- mrmarket://schemas/query_data_response
- mrmarket://capabilities

## Prompts
Not captured

## Metadata
- Owner: ai.mrmarket
- Version: 1.0.0
- Runtime: Streamable Http
- Transports: HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Jun 6, 2026
- Source: https://registry.modelcontextprotocol.io