Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TickerRisk MCP Server Is it safe to sell a 3-week put on AAPL?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Check an options trade for hidden catalysts before you sell premium — from inside Claude, ChatGPT, or Cursor.
An MCP server that lets an AI assistant answer questions like "is it safe to sell a 30-day put on HPE?" with real event data instead of a guess.
The problem it solves: a fat option premium is usually the market pricing in a known upcoming event — an earnings report, an FDA decision, a court date — not free money. Some screeners flag earnings; few check the wider event calendar. This one scores every candidate across earnings, FDA, legal, SEC and clinical events landing inside the expiry window, and filters out the traps.
You: Is it safe to sell a 4-week put on INTC?
Claude: [calls scan_ticker]
INTC scores 100/100 (HIGH) over a 4-week window. Earnings land in 4 days,
inside your expiry. The premium is pricing that gap — 279% annualized on
the $88 put is compensation for event risk, not an edge.Risk is horizon-dependent, and that is the whole point. The same stock:
Ticker | 1-week window | 4-week window | Why it changes |
AAPL | 51 (MEDIUM) | 97 (HIGH) | Earnings sit in week 3 |
KO | 22 (LOW) | 62 (MEDIUM) | Earnings enter the window |
Sell a weekly and you are fine. Sell a monthly on the same ticker and you have sold straight through an earnings report. A screener that shows one number cannot tell you that.
Related MCP server: RiskLens MCP
Add to your claude_desktop_config.json:
macOS/Linux — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tickerrisk": {
"command": "uvx",
"args": ["tickerrisk-mcp"]
}
}
}Restart Claude Desktop. You should see the TickerRisk tools in the tool menu.
claude mcp add tickerrisk -- uvx tickerrisk-mcpIn ~/.cursor/mcp.json:
{
"mcpServers": {
"tickerrisk": { "command": "uvx", "args": ["tickerrisk-mcp"] }
}
}git clone https://github.com/Tickerrisk/tickerrisk-mcp
cd tickerrisk-mcp
pip install -e .
tickerrisk-mcpTool | What it answers |
| "How risky is selling an option on X over the next N weeks?" |
| "What cash-secured puts can I sell this week without an earnings trap?" |
| "What calls can I sell against shares I already own?" |
| "Which of these stocks is safest to sell premium on right now?" |
scan_ticker(ticker, expiry_weeks=4)Returns a 0–100 catalyst-risk score (higher = riskier) with the events driving it: earnings date and whether it falls in the window, FDA/clinical milestones, legal filings, SEC events, implied volatility, IV Rank, and the expected move.
Bands: ≥70 HIGH · 45–69 MEDIUM · <45 LOW
find_wheel_candidates(week, risk, max_risk, min_put_oi, sector, limit)Scans the S&P 500 for cash-secured puts and returns only names whose catalyst score over
the option's own expiry window is under max_risk. Flags any candidate whose earnings land
before expiry.
find_covered_calls(week, risk, max_risk, min_call_oi, sector, limit)Same gating for the call side. Income is computed from time value only, so in-the-money strikes do not show inflated yields.
compare_tickers(tickers, expiry_weeks=4)Side-by-side catalyst risk for up to 25 symbols on one horizon.
No signup needed to start. Access follows tickerrisk.com's normal model:
First 24 hours — full access, no account, keyed to your IP
After that — a free account at tickerrisk.com adds 14 days
The strategy scanners (find_wheel_candidates, find_covered_calls, compare_tickers)
read cached data and stay available
To authenticate an existing account, set a token:
{
"mcpServers": {
"tickerrisk": {
"command": "uvx",
"args": ["tickerrisk-mcp"],
"env": { "TICKERRISK_TOKEN": "your-jwt-here" }
}
}
}Variable | Default | Purpose |
| (none) | JWT for an existing account |
|
| Override the API host |
|
| Request timeout in seconds |
Being straight about what this is and is not:
Catalyst data — earnings dates, SEC filings, court records (CourtListener), ClinicalTrials.gov, and news. Public sources, so incomplete or delayed entries happen.
Option premiums are indicative, not live NBBO. Quotes are roughly 15 minutes delayed and estimated where no bid exists (marked in the output). Always confirm in your broker before trading.
Outside US market hours (9:30–16:00 ET) quotes go stale and candidate lists thin out. This is upstream data reality, not a bug.
The score is not a prediction. It measures scheduled event exposure and volatility. A LOW score does not mean a stock cannot drop; it means no known catalyst was found in that window.
Not financial advice. For research only.
Being accurate about this, because the differentiator is narrower than most tools claim:
Earnings-date checking is not unique. Barchart's options screener has a "Flag Earnings" option that marks contracts whose next earnings date falls on or before expiration. Market Chameleon tracks biotech catalysts and links them to option chains. If earnings alone is what you need, those are mature tools with real-time data and far more filters — use them.
What this tool does differently is combine five event types — earnings, FDA decisions, legal filings, SEC events and clinical milestones — into a single 0–100 score tied to your expiry window, and filter on it by default rather than showing an optional flag column. Court records as an options-risk input in particular is something we have not found elsewhere.
So: if you want the deepest screener, use Barchart or Option Samurai. If you want one number that answers "is there anything scheduled inside this expiry", that is what this is.
Website — tickerrisk.com
Wheel scanner — tickerrisk.com/wheel
Covered calls — tickerrisk.com/covered-calls
MIT
mcp-name: io.github.PasiutusVovere/tickerrisk-mcp
Compare catalyst risk across several stocks at once, over the same expiry window.
Use this when someone is choosing between tickers to sell options on, or asks which of several stocks is the safest bet for a given expiry.
Faster than scanning one at a time. Only returns tickers already in the cache (all S&P 500 names are); anything missing is listed so it can be scanned individually with scan_ticker.
Args: tickers: Comma-separated symbols, e.g. "AAPL, MSFT, NVDA". Up to 25. expiry_weeks: Expiry horizon in weeks (1-52), applied to every ticker.
| Name | Required | Description | Default |
|---|---|---|---|
| tickers | Yes | ||
| expiry_weeks | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it discloses a significant behavioral trait: results are limited to tickers already in the cache (all S&P 500 names), with missing tickers reported back rather than silently dropped. It does not mention auth needs or rate-limit behavior, so a small gap remains for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is short, front-loaded on purpose and usage, then parameters. The 'Faster than scanning one at a time' sentence is mildly redundant but reinforces the usage rationale rather than wasting space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is unnecessary. Given two parameters and no annotations, the description covers purpose, when-to-use, the cache limitation, the fallback to scan_ticker, and both parameter formats — nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description fully compensates: it gives the comma-separated string format with an example ('AAPL, MSFT, NVDA'), a hard cap of 25, the unit and valid range for expiry_weeks (1-52 weeks), and notes it applies to every ticker. This is more meaning than the bare schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb (compare) and resource (catalyst risk across several stocks) with a scoping constraint (same expiry window). It distinguishes itself from siblings like scan_ticker by operating on multiple tickers at once, which an agent can grasp without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it ('choosing between tickers to sell options on', 'which of several stocks is the safest bet') and names the alternative for the single-ticker case (scan_ticker). Both the selection condition and the fallback path are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find covered-call candidates that have no hidden catalyst in the expiry window.
Use this when someone asks what calls to sell against shares they own, for covered-call income ideas, or how to generate yield on a stock position.
Same catalyst gating as the wheel scanner. Income is computed from TIME VALUE only, so in-the-money strikes do not show inflated yields.
Args: week: Expiry bucket — "this", "next", "two", "three", "month", or "all". risk: "conservative" (further out of the money, more likely to keep the shares), "balanced", or "aggressive" (nearer the money, more premium, more likely to be called away). max_risk: Maximum catalyst-risk score to allow, 0-100. min_call_oi: Minimum call open interest, for tradeable results. sector: Optional GICS sector filter. Empty means all sectors. limit: How many candidates to return (1-25).
| Name | Required | Description | Default |
|---|---|---|---|
| risk | No | balanced | |
| week | No | all | |
| limit | No | ||
| sector | No | ||
| max_risk | No | ||
| min_call_oi | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the catalyst-gating rule, that yields are computed from TIME VALUE only so ITM strikes are not inflated, and that max_risk/min_call_oi act as safety and liquidity gates. It stops short of stating read-only/non-mutating status or any rate/limitation behavior, which keeps it out of 5 territory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and usage lines are front-loaded, followed by two sentences of behavioral context, then a compact parameter list. Given the 0% schema coverage, listing each argument is not redundant padding but the only place that information exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. All six optional parameters are explained, defaults are visible in the schema, and the tool's screening logic and risk gates are stated, leaving nothing an agent needs in order to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it fully does: it supplies the enumerated values for week ('this', 'next', 'two', 'three', 'month', 'all') and for risk, explains what each risk level means for assignment likelihood, and gives ranges for max_risk (0-100) and limit (1-25). These are semantics the bare schema cannot provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: 'Find covered-call candidates that have no hidden catalyst in the expiry window.' It also implicitly separates the tool from the sibling find_wheel_candidates by noting 'Same catalyst gating as the wheel scanner,' so an agent can distinguish the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage context is given: 'Use this when someone asks what calls to sell against shares they own, for covered-call income ideas, or how to generate yield on a stock position.' However, it never names when NOT to use it (e.g., to use find_wheel_candidates for cash-secured puts, or scan_ticker for a single-name view), so the routing guidance is clear but not exclusive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find cash-secured put candidates (the wheel strategy) that have no hidden catalyst in the expiry window.
Use this when someone asks what puts to sell this week, for wheel or cash-secured-put ideas, for "safe premium" to collect, or which stocks pay well without an earnings report coming up.
Scans the whole S&P 500 and returns only names whose catalyst-risk score over the option's own expiry window is under max_risk — so candidates with earnings, FDA decisions or legal events inside the window are filtered out rather than surfaced as fake high-yield opportunities.
Args: week: Expiry bucket — "this" (1-7 days), "next" (8-14), "two", "three", "month" (1-35), or "all" (up to 45 days). "all" returns the most results. risk: How close to the money to sell — "conservative" (~0.20 delta, further out, safer), "balanced" (~0.30), or "aggressive" (~0.40, more premium, more assignment risk). max_risk: Maximum catalyst-risk score to allow, 0-100. 55 is a sensible default; lower it to 40 for a stricter list. min_put_oi: Minimum put open interest, to keep results actually tradeable. Keep at 100 during market hours. sector: Optional GICS sector filter, e.g. "Technology", "Health Care", "Financials". Empty means all sectors. limit: How many candidates to return (1-25).
| Name | Required | Description | Default |
|---|---|---|---|
| risk | No | balanced | |
| week | No | all | |
| limit | No | ||
| sector | No | ||
| max_risk | No | ||
| min_put_oi | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that the scan covers the whole S&P 500, that results are pre-filtered by catalyst-risk score against the option's own expiry window, and why risky names are excluded rather than surfaced. It omits any note on auth, rate limits, or runtime cost of a full-index scan.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the purpose and the key differentiator before the usage triggers and arg docs. Slightly long, but each paragraph earns its place; the arg entries are structured rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation. Given a 6-param tool with no annotations and no schema descriptions, the description supplies everything an agent needs to call it correctly: intent, filtering behavior, and per-parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and there are 6 parameters, so this had to compensate fully — and it does. Every parameter gains meaning the schema lacks: week buckets with day ranges and the note that 'all' returns most results, risk levels with delta anchors, a default and tuning hint for max_risk, and a market-hours instruction for min_put_oi, plus a valid range for limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find cash-secured put candidates (the wheel strategy)') plus a critical scope qualifier ('no hidden catalyst in the expiry window'). The catalyst-filter distinction separates it from the covered-call sibling and from generic screeners without requiring a schema read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete trigger phrases ('what puts to sell this week', 'safe premium', 'stocks pay well without an earnings report coming up'), which maps cleanly onto user intent. It does not explicitly name find_covered_calls as the alternative for the exit half of the wheel, so there is no stated when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check how risky it is to sell or buy an option on a stock, over a specific expiry window.
Use this whenever someone asks whether it is safe to sell a put or a covered call on a ticker, whether a premium is "too good", what could gap a stock before expiry, or what catalysts are coming up for a company.
Returns a 0-100 catalyst-risk score (higher = riskier) plus the specific events driving it: earnings dates, FDA decisions, legal filings, SEC events, and the implied-volatility expected move. The key idea is that risk depends on the expiry window — a stock can be LOW risk for a 1-week option and HIGH risk for a 6-week option that spans an earnings report.
Args: ticker: Stock symbol, e.g. "AAPL", "HPE", "KO". expiry_weeks: How many weeks until the option expires (1-52). Match this to the actual trade being considered. Defaults to 4 (~30 DTE, the typical premium-selling horizon).
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | ||
| expiry_weeks | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, and it does explain the return shape (0-100 score plus driving events and the IV expected move) and the central mechanic that risk is window-dependent. It does not disclose whether the call is read-only, data freshness/source, or any rate/latency characteristics, which is the remaining gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the key risk-window insight are front-loaded, and the sentence about LOW risk for 1-week versus HIGH risk for a 6-week window spanning earnings is high-value. It runs a bit long for two parameters, and the Args block partly restates schema fields, but given 0% schema coverage that restatement earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description is not obligated to explain return values, yet it still names the score and driving events. Combined with the parameter guidance and the expiry-window model, an agent has everything needed to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates: it gives example ticker values, states the expiry_weeks range (1-52), explains the default of 4 as ~30 DTE and why that is the typical premium-selling horizon. This is meaningfully more than the bare integer schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (assess option-selling/buying risk on a stock over an expiry window) and the concrete artifact it produces (a 0-100 catalyst-risk score). Sibling names like find_covered_calls and find_wheel_candidates describe other option workflows, and this one is clearly the risk-scan, so the agent can distinguish it without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Strong trigger-based guidance: it enumerates the user questions that select this tool ('is it safe to sell a put', 'is the premium too good', 'what could gap the stock', 'what catalysts are coming up'). It does not explicitly name the sibling tools or state when NOT to use it (e.g. versus find_covered_calls), so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3compare_tickersfind_covered_callsfind_wheel_candidatesscan_tickerScored across 4 tools
Each tool targets a clearly distinct action: scan_ticker (single-ticker risk), compare_tickers (batch comparison), find_wheel_candidates (put screening), and find_covered_calls (call screening). The single-vs-batch and put-vs-call boundaries are explicit in the descriptions, leaving little room for misselection.
All four names follow a consistent verb_noun snake_case pattern (scan_ticker, compare_tickers, find_wheel_candidates, find_covered_calls). The plural 'tickers' in compare is minor and still readable.
Four tools is a lean but coherent surface where each earns its place, though it sits at the thin end of the ideal range. No obvious redundancy or bloat.
The workflow is well covered: single scan, multi-ticker comparison, and both screener directions (puts and calls), with missing tickers flagged for individual scanning. Minor gaps exist around analyzing existing positions or custom non-cached tickers, but agents can work around them.
Explainable model signals, drivers, news sentiment, SEC filings and macro data for US stocks.
Verified biotech catalyst calendar (PDUFA/AdComm/trial readouts) anchored to official sources.
Options-implied earnings moves, 10y implied-vs-actual history, IV rush/crush, scanner, simulator.
Real-time news with bias scoring, live market data, and AI-powered options pricing
