Analyzes options trades for hidden catalysts like earnings, FDA decisions, and legal filings to assess event risk within specific expiry windows.
Also known as Tickerrisk/tickerrisk-mcp, tickerrisk-mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- 127
- Latest version
- 0.1.3
- Last commit
- Sep 27, 2026
- License
- MIT
What is TickerRisk MCP?
TickerRisk analyzes options trades for hidden catalysts like earnings, FDA decisions, and legal filings to assess event risk within specific expiry windows. It exposes 4 tools, such as scan_ticker, find_wheel_candidates, find_covered_calls.
Summary generated from the project's README
About TickerRisk MCP server
Analyzing options trades for hidden catalysts like earnings, FDA decisions, and legal filings is what TickerRisk enables for traders using Claude, ChatGPT, or Cursor. It provides a catalyst-risk score from 0 to 100 to help users determine if a high option premium is due to actual edge or simply compensation for an upcoming event within a specific expiry window. The server integrates five distinct event types, including SEC filings and clinical milestones, to assess risk based on the user's chosen time horizon.
Users can run this server locally via uvx or by installing from source. It requires no initial signup, as the first 24 hours are accessible via IP address, though a free account provides extended access. For existing users, authentication is handled through a TICKERRISK_TOKEN environment variable. The toolset includes scan_ticker for individual risk assessment, find_wheel_candidates for cash-secured puts, find_covered_calls for income generation, and compare_tickers for evaluating up to 25 symbols side-by-side.
What you can do with it
- 1Assess individual trade riskDetermine if a specific option's premium is inflated by an upcoming earnings report or other scheduled event.
- 2Find safe wheel strategiesScan the S&P 500 for cash-secured puts that do not have earnings traps within the expiration period.
- 3Compare multiple stock risksEvaluate the catalyst exposure of several different tickers simultaneously over a set number of weeks.
Written from the project's README. Every use case is checked against a quote from it.
How to install TickerRisk MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall TickerRisk MCP in Claude Code
$ claude mcp add --env 'TICKERRISK_TOKEN=<YOUR_TICKERRISK_TOKEN>' tickerrisk-mcp -- uvx tickerrisk-mcpInstall TickerRisk MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tickerrisk-mcp": {
"command": "uvx",
"args": [
"tickerrisk-mcp"
],
"env": {
"TICKERRISK_TOKEN": "<YOUR_TICKERRISK_TOKEN>"
}
}
}
}Install TickerRisk MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tickerrisk-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"tickerrisk-mcp"
],
"env": {
"TICKERRISK_TOKEN": "<YOUR_TICKERRISK_TOKEN>"
}
}
}
}Install TickerRisk MCP in VS Code CLI
$ code --add-mcp '{"name":"tickerrisk-mcp","type":"stdio","command":"uvx","args":["tickerrisk-mcp"],"env":{"TICKERRISK_TOKEN":"<YOUR_TICKERRISK_TOKEN>"}}'Install TickerRisk MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tickerrisk-mcp": {
"command": "uvx",
"args": [
"tickerrisk-mcp"
],
"env": {
"TICKERRISK_TOKEN": "<YOUR_TICKERRISK_TOKEN>"
}
}
}
}Install TickerRisk MCP in Codex
$ codex mcp add tickerrisk-mcp --env 'TICKERRISK_TOKEN=<YOUR_TICKERRISK_TOKEN>' -- uvx tickerrisk-mcpInstall TickerRisk MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tickerrisk-mcp] command = "uvx" args = ["tickerrisk-mcp"] [mcp_servers.tickerrisk-mcp.env] TICKERRISK_TOKEN = "<YOUR_TICKERRISK_TOKEN>"
Install TickerRisk MCP in Gemini CLI
$ gemini mcp add -s user -e 'TICKERRISK_TOKEN=<YOUR_TICKERRISK_TOKEN>' tickerrisk-mcp uvx -- tickerrisk-mcpInstall TickerRisk MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tickerrisk-mcp": {
"command": "uvx",
"args": [
"tickerrisk-mcp"
],
"env": {
"TICKERRISK_TOKEN": "<YOUR_TICKERRISK_TOKEN>"
}
}
}
}TickerRisk MCP tools 4
Detected from the READMEscan_tickerfind_wheel_candidatesfind_covered_callscompare_tickers
| scan_ticker | — | |
| find_wheel_candidates | — | |
| find_covered_calls | — | |
| compare_tickers | — |
Configuration
TICKERRISK_TOKENSecretOptional JWT for an existing TickerRisk account. Without it, anonymous access applies: full access for 24 hours, then a free account extends it.
TICKERRISK_BASE_URLOverride the API host. Defaults to https://tickerrisk.com
| Name | Description | |
|---|---|---|
| TICKERRISK_TOKEN | Optional JWT for an existing TickerRisk account. Without it, anonymous access applies: full access for 24 hours, then a free account extends it. | Secret |
| TICKERRISK_BASE_URL | Override the API host. Defaults to https://tickerrisk.com |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletickerrisk/tickerrisk-mcp is public and reachablegithub.com/tickerrisk/tickerrisk-mcp ↗Pass
- Package names this repository as its sourcetickerrisk-mcp names tickerrisk/tickerrisk-mcp as sourcepypi.org/project/tickerrisk-mcp/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-27github.com/tickerrisk/tickerrisk-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from tickerrisk-mcpPass
- No critical advisory in the package or its dependencies30 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model4 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 handshakeNot checked
README
View on GitHubTickerRisk MCP Server
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.
Why this is different
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.
Install
Claude Desktop
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 Code
claude mcp add tickerrisk -- uvx tickerrisk-mcp
Cursor
In ~/.cursor/mcp.json:
{
"mcpServers": {
"tickerrisk": { "command": "uvx", "args": ["tickerrisk-mcp"] }
}
}
From source
git clone https://github.com/Tickerrisk/tickerrisk-mcp
cd tickerrisk-mcp
pip install -e .
tickerrisk-mcp
Tools
| Tool | What it answers |
|---|---|
scan_ticker |
"How risky is selling an option on X over the next N weeks?" |
find_wheel_candidates |
"What cash-secured puts can I sell this week without an earnings trap?" |
find_covered_calls |
"What calls can I sell against shares I already own?" |
compare_tickers |
"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.
Access and authentication
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" }
}
}
}
Environment variables
| Variable | Default | Purpose |
|---|---|---|
TICKERRISK_TOKEN |
(none) | JWT for an existing account |
TICKERRISK_BASE_URL |
https://tickerrisk.com |
Override the API host |
TICKERRISK_TIMEOUT |
45 |
Request timeout in seconds |
Data and limitations
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.
How it compares
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.
Links
- Website — tickerrisk.com
- Wheel scanner — tickerrisk.com/wheel
- Covered calls — tickerrisk.com/covered-calls
License
MIT
mcp-name: io.github.PasiutusVovere/tickerrisk-mcp
TickerRisk MCP questions
How do I add TickerRisk MCP to Claude Code?
Run claude mcp add --env 'TICKERRISK_TOKEN=<YOUR_TICKERRISK_TOKEN>' tickerrisk-mcp -- uvx tickerrisk-mcp in your terminal. Add --scope user to make it available in every project.
How do I add TickerRisk 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 TickerRisk MCP provide?
It exposes 4 tools, including scan_ticker, find_wheel_candidates, find_covered_calls, compare_tickers.
What kind of events does TickerRisk track?
The server tracks earnings reports, FDA/clinical milestones, legal filings, SEC events, and court records.
Is the risk score a prediction of stock movement?
No, the score measures scheduled event exposure and volatility rather than predicting price direction.
How accurate is the option premium data?
Option premiums are indicative and roughly 15 minutes delayed; they are not live NBBO quotes.