Analytical engine for US-listed equities: screens, rankings, and event studies in plain English.
ai.mrmarket/mrmarket-mcp (MCP Server)
The ai.mrmarket/mrmarket-mcp server is an analytical engine for US-listed equities. It provides capabilities for screens, rankings, and event studies expressed in plain English. Designed for the Model Context Protocol (MCP), it exposes 9 tools to support equity analysis workflows.
🛠️ Key Features
US-listed equities analytics
Screens, rankings, and event studies
Plain-English outputs
MCP server with 9 tools
🚀 Use Cases
Screening equities based on criteria
Producing ranked lists of stocks
Running event studies for equity-related events
⚡ Developer Benefits
Plain-English phrasing for analytical results
Tool access count: 9
Built around Model Context Protocol compatibility
⚠️ Limitations
Focused on US-listed equities
Scope described only as screens, rankings, and event studies
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.
Parameters1
topic
string
optional
Optional section to deep-dive. Default: "overview" — short tour of everything.
Raw schema
{
"type": "object",
"properties": {
"topic": {
"description": "Optional section to deep-dive. Default: \"overview\" — short tour of everything.",
"type": "string",
"enum": [
"overview",
"tools",
"examples",
"limits",
"cost",
"troubleshoot",
"help"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
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
- Derived metrics composed on the fly: any ratio of two fields, growth of any metric,
rolling stats on any series — the data catalog lists ingredients, you may mix them
- Period-over-period changes: QoQ, YoY, multi-year
- Rolling averages, trend slopes, volatility, beta vs a benchmark, correlation,
median/percentiles, quartile buckets, max drawdown, 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
Parameters6
question
string
required
ONE natural-language financial question, max 100 words (hard limit — longer is rejected as QUESTION_TOO_LONG, free of charge). Not SQL. Be precise, not redundant: metric(s) + universe/filters + time range is enough; the server picks columns and thresholds. Put ticker lists in `symbols`, never in this text. If 100 words feels tight, you are bundling multiple questions — split them into separate calls (see mrmarket://capabilities for the split test).
max_rows
number
optional
Optional caller-side row cap. There is NO default cap — by default the server returns every row the SQL produced. Only pass this when you deliberately want a preview (e.g., max_rows: 10).
symbols
array
optional
Explicit ticker universe for this question (e.g., a screening batch). STRONGLY preferred over pasting long ticker lists into `question`: the list is applied mechanically as a symbol filter (exact, order-independent), keeps the question readable, and is cheaper. Phrase the question generically ("Find every golden cross event…") and put the tickers here.
clarifications
array
optional
Answers to a prior clarification_needed response (pass each question verbatim with your chosen answer). Use together with clarification_mode: "return" for a two-step round-trip.
clarification_mode
string
optional
"auto" (default): ambiguous questions are resolved via elicitation or sensible server defaults in one call. "return": the server returns status "clarification_needed" with the questions + recommended defaults and does NOT proceed (and does not charge); answer by re-calling query_data with `clarifications`. Use "return" when silent defaults are not acceptable for your user.
visualize
boolean
optional
Opt-in charting for the shareable view_url. Default false returns a plain table link (cheapest). Set true when the user wants a chart or stat card: the link is then rendered with the chart type the engine picks from the data shape — a single-row result becomes a "stat" card, a multi-period series a line chart, etc. Does not change the JSON rows you receive, only how the view_url renders.
Raw schema
{
"type": "object",
"properties": {
"question": {
"type": "string",
"maxLength": 4000,
"description": "ONE natural-language financial question, max 100 words (hard limit — longer is rejected as QUESTION_TOO_LONG, free of charge). Not SQL. Be precise, not redundant: metric(s) + universe/filters + time range is enough; the server picks columns and thresholds. Put ticker lists in `symbols`, never in this text. If 100 words feels tight, you are bundling multiple questions — split them into separate calls (see mrmarket://capabilities for the split test)."
},
"max_rows": {
"description": "Optional caller-side row cap. There is NO default cap — by default the server returns every row the SQL produced. Only pass this when you deliberately want a preview (e.g., max_rows: 10).",
"type": "number"
},
"symbols": {
"description": "Explicit ticker universe for this question (e.g., a screening batch). STRONGLY preferred over pasting long ticker lists into `question`: the list is applied mechanically as a symbol filter (exact, order-independent), keeps the question readable, and is cheaper. Phrase the question generically (\"Find every golden cross event…\") and put the tickers here.",
"maxItems": 2000,
"type": "array",
"items": {
"type": "string"
}
},
"clarifications": {
"description": "Answers to a prior clarification_needed response (pass each question verbatim with your chosen answer). Use together with clarification_mode: \"return\" for a two-step round-trip.",
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"answer": {
"type": "string"
}
},
"required": [
"question",
"answer"
]
}
},
"clarification_mode": {
"description": "\"auto\" (default): ambiguous questions are resolved via elicitation or sensible server defaults in one call. \"return\": the server returns status \"clarification_needed\" with the questions + recommended defaults and does NOT proceed (and does not charge); answer by re-calling query_data with `clarifications`. Use \"return\" when silent defaults are not acceptable for your user.",
"type": "string",
"enum": [
"auto",
"return"
]
},
"visualize": {
"description": "Opt-in charting for the shareable view_url. Default false returns a plain table link (cheapest). Set true when the user wants a chart or stat card: the link is then rendered with the chart type the engine picks from the data shape — a single-row result becomes a \"stat\" card, a multi-period series a line chart, etc. Does not change the JSON rows you receive, only how the view_url renders.",
"type": "boolean"
}
},
"required": [
"question"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
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.
Parameters1
cursor
string
required
The opaque continuation cursor from a prior response's `pagination.next_cursor`. Paste it exactly. Do NOT pass a question here — fetch_page returns the next page of an existing result and never runs a new query.
Raw schema
{
"type": "object",
"properties": {
"cursor": {
"type": "string",
"description": "The opaque continuation cursor from a prior response's `pagination.next_cursor`. Paste it exactly. Do NOT pass a question here — fetch_page returns the next page of an existing result and never runs a new query."
}
},
"required": [
"cursor"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
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.
The catalog lists RAW INGREDIENTS; query_data accepts RECIPES. Any field can be combined
with any other in one question — ratios of two fields, growth of any metric, rolling
stats, group medians, cohort-relative z-scores, benchmark-relative betas. A metric
missing from the catalog by name is still answerable if it's computable from the fields
(the overview's `composition` section lists the patterns).
Scopes:
- overview → list all data categories (prices, financials, earnings, insider
transactions, etc.) + coverage depth + key fields + computed
metrics + composition patterns. 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 → pre-defined computed metrics (ROIC, FCF yield, D/E, ROE, ROA,
margins, growth/CAGR, volatility, drawdown, beta, z-score, median…).
- search → keyword search across field names, categories, computed metrics,
and composition patterns. Pass search_term: 'volatility', 'capex', etc.
Parameters3
scope
string
required
Use "category" (or "entity" as alias) for a specific data category.
entity
string
optional
Category name for scope "category" — e.g. "Stock Prices", "Income Statements", "Earnings".
search_term
string
optional
Raw schema
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": [
"overview",
"category",
"entity",
"computed_metrics",
"search"
],
"description": "Use \"category\" (or \"entity\" as alias) for a specific data category."
},
"entity": {
"description": "Category name for scope \"category\" — e.g. \"Stock Prices\", \"Income Statements\", \"Earnings\".",
"type": "string"
},
"search_term": {
"type": "string"
}
},
"required": [
"scope"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
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.
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.
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).
Parameters2
limit
integer
optional
How many recent queries to return. Default 10, max 50.
status
string
optional
Filter by outcome. "error" includes timeouts. Default "all".
Raw schema
{
"type": "object",
"properties": {
"limit": {
"description": "How many recent queries to return. Default 10, max 50.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50
},
"status": {
"description": "Filter by outcome. \"error\" includes timeouts. Default \"all\".",
"type": "string",
"enum": [
"all",
"success",
"error"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
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
Parameters3
description
string
required
Required. Short free-text description of what went wrong or what you want. One or two sentences is plenty — support reads every report. Max 4000 chars.
category
string
optional
Optional. Defaults to "general" if omitted.
query_id
string
optional
Optional but strongly recommended for query-specific reports. The `query_id` from the `query_data` response you want support to look at (format: `mcp_<timestamp>_<n>`). With it, the server auto-attaches the run's status, error_code, row_count, execution_time, and the original question snippet to the ticket — the user does not need to dictate any of that. If you don't have the query_id at hand, call `recent_queries` first to look it up.
Raw schema
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Required. Short free-text description of what went wrong or what you want. One or two sentences is plenty — support reads every report. Max 4000 chars."
},
"category": {
"description": "Optional. Defaults to \"general\" if omitted.",
"type": "string",
"enum": [
"wrong_data",
"bug",
"slow",
"feature_request",
"general"
]
},
"query_id": {
"description": "Optional but strongly recommended for query-specific reports. The `query_id` from the `query_data` response you want support to look at (format: `mcp_<timestamp>_<n>`). With it, the server auto-attaches the run's status, error_code, row_count, execution_time, and the original question snippet to the ticket — the user does not need to dictate any of that. If you don't have the query_id at hand, call `recent_queries` first to look it up.",
"type": "string"
}
},
"required": [
"description"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
list_tickets
List the user's own report_issue tickets (newest first). Zero LLM cost, zero credits.
Use this to look up a ticket you (or the user) filed earlier — e.g. to quote the full
ticket_id when following up with support, or to check what was already reported before
filing a duplicate. Each entry returns:
- ticket_id (full UUID — quote this in follow-ups)
- category (wrong_data | bug | slow | feature_request | general)
- preview (first 200 chars of the report text)
- query_id (the query the ticket was filed against, when attached)
- created_at_iso
Parameters1
limit
integer
optional
How many tickets to return. Default 10, max 50.
Raw schema
{
"type": "object",
"properties": {
"limit": {
"description": "How many tickets to return. Default 10, max 50.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 50
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}