io.github.benjamin-di/earnings-watch
Earnings Watch exposes verified earnings-calendar data, evidence, documents, personal watchlists, change feeds, and optional Outlook calendar planning through MCP.
List upcoming verified earnings dates with timing uncertainty.
Retrieve public events with evidence, revisions, and bounded history.
List official results-document links and verification status.
Read the shared change feed using a cursor.
View follows and pending registration states.
Follow or unfollow issuers, resolving ambiguous tickers via candidates.
Plan optional external Outlook calendar operations and acknowledge confirmed results.
Read catalogue counts and maintenance status without model calls.
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., "@io.github.benjamin-di/earnings-watch show upcoming earnings for my watchlist this week"
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.
Earnings Watch
Verified issuer earnings calendars and results documents through a CLI, Python API and MCP server. Models propose dates; deterministic checks require quoted evidence and consistent issuer, period and timing. A call time never silently becomes a publication time.
Calendar updates are optional. Earnings Watch produces an operation plan; your MCP client uses its external Outlook app to apply it and acknowledges confirmed writes. No Microsoft credentials or calendar SDK are required by this package.
Maintained source and contributions: benjamin-di/earnings-watch. See Source and releases.
Requires Python 3.12+. Install the published package with uv tool install earnings-watch, or develop from a source checkout:
make bootstrap
uv run earnings-watch init
uv run earnings-watch doctor
uv run earnings-watch sources import examples/sources.yaml
uv run earnings-watch watch EXAMPLE
uv run earnings-watch upcoming --format jsonThe example uses reserved domains and fictional data; replace its source URLs and issuer metadata before fetching. There is no bundled issuer universe or market-data subscription.
Maintenance and models
Serving reads SQLite and updates personal follows/ledgers; it never fetches issuer pages or calls a model. Run maintenance separately:
uv run earnings-watch sweep --dry-run
uv run earnings-watch sweep
uv run earnings-watch sweep --docs-only
uv run earnings-watch workerThe default backend is none: it preserves existing dates and still polls official release providers. To extract new dates, install and sign into your own Claude Code or Codex CLI, then configure it in earnings-watch.toml:
[llm]
backends = ["claude-code", "codex", "none"]
max_calls_per_run = 20Supported minimum versions are Claude Code 2.1.312 and Codex 0.164.0. Run earnings-watch doctor --live to check capabilities and an optional model canary. The package has no login flow. Model usage follows your CLI account's limits and terms. Only an explicit sign-in or account-limit refusal, or a configured Codex endpoint that is unreachable or failing before any output, tries the next backend; a timed-out run is not repeated in the same tick.
Codex runs with --ignore-user-config. To send it through an OpenAI Responses-compatible endpoint, set both codex_base_url and codex_key_env (the name of the environment variable holding its key) under [llm]; the key itself never goes in the file. Use https:// for any endpoint that is not on the local host. Claude Code receives ANTHROPIC_BASE_URL and CLAUDE_CODE_MAX_RETRIES from the environment, so a bounded retry count lets an unavailable endpoint fail before the task timeout.
Related MCP server: corporate-events-mcp
MCP
A local client configuration, after initialization:
{"mcpServers":{"earnings":{"command":"earnings-watch","args":["serve","--stdio"]}}}Tool | Purpose |
| Bounded upcoming dates with timing uncertainty |
| Evidence, revisions and recent history |
| Official result-document links and verification status |
| Cursor-based public change feed |
| Your follows and registration states |
| Follow an issuer; queue registration or resolve ambiguity |
| Remove a manual follow |
| Plan optional external calendar operations |
| Record confirmed operations from a signed plan |
| Catalogue and maintenance status |
Prompts: earnings_briefing, results_brief, sync_to_my_outlook. Resource: earnings://upcoming.ics. Exact times require verified clock and timezone evidence; otherwise calendar entries are all-day. Outlook operations never include attendees.
HTTP standalone mode uses a separate bearer token per person at /users/<id>/mcp. Gateway mode accepts a configured backend bearer and an immutable subject header from the admission gateway at /mcp. These modes are separate trust boundaries; see permissions.
Connections page and notifications
The optional Connections page provides Upcoming, Your companies, Notifications and Calendar in one place. Sign in, add companies or preview a holdings import, then subscribe to your private calendar feed. Facts are shared; holdings, watchlists, mutes, preferences and receipts are personal.
Results-out notifications are enabled for new people. Daily briefs and urgent changes are optional. Mail submission requires a separately configured transport; the server and acquisition worker never send messages themselves.
Docker Compose
cp earnings-watch.example.toml earnings-watch.toml
docker compose build
docker compose run --rm server init
docker compose run --rm server users add example
docker compose up -dSave the returned token privately and use it only on that person's HTTP path. The server binds to loopback by default. Both images run as uid 1000; Compose drops capabilities, prevents privilege escalation and mounts the root filesystem read-only. The worker image includes pinned model CLIs; their auth volume is optional with backends=["none"]. Configure CLI sign-in outside the read-only worker before enabling model maintenance. Protect auth files and the data volume from other users.
Use --config PATH, --person ID, and --json with the CLI. Settings come from TOML and EARNINGS_WATCH_* environment variables. See operations, architecture, providers and design decisions.
Development
make check verifies lock drift, lint, formatting, types, dependency boundaries, offline tests and wheel/source builds. Tests use synthetic issuers and fake network/model/account boundaries. Real-model and real-page checks are separate operator gates. Read CONTRIBUTING.md and SECURITY.md.
See implementation status for completed capabilities, release gates and the production adapter work still required before cutover.
Available Tools
10 toolsearnings_calendar_ackEarnings Calendar AckCIdempotent
R1. Record confirmed external operations; reject stale or altered plans.
Inputs: handle (required), results (required). Returns: object
earnings_calendar_planEarnings Calendar PlanCRead-onlyIdempotent
R0. Plan optional Outlook operations. Apply through your external Outlook app.
Inputs: full, sink, event_ids. Returns: object
earnings_changesEarnings ChangesBRead-onlyIdempotent
R0. Read the shared change feed; keep the returned cursor for next time.
Inputs: limit, cursor. Returns: object
earnings_documentsEarnings DocumentsCRead-onlyIdempotent
R0. List official result-document links and their verification status.
Inputs: limit, roles, scope, since, +2 more. Returns: object
earnings_get_eventsEarnings Get EventsCRead-onlyIdempotent
R0. Read up to 20 public events with evidence and bounded history.
Inputs: ids (required). Returns: object
earnings_statusEarnings StatusBRead-onlyIdempotent
R0. Read catalogue counts and maintenance status without model calls.
Inputs: no named parameters. Returns: object
earnings_unwatchEarnings UnwatchCIdempotent
R1. Remove your manual follow; public history is retained.
Inputs: ticker (required), exchange. Returns: object
earnings_upcomingEarnings UpcomingCRead-onlyIdempotent
R0. List upcoming verified dates, including explicit timing uncertainty.
Inputs: days, limit, scope, types, +2 more. Returns: object
earnings_watchEarnings WatchCIdempotent
R1. Follow an issuer for yourself; ambiguous tickers return candidates.
Inputs: ticker (required), isin, name, exchange. Returns: object
earnings_watchlistEarnings WatchlistBRead-onlyIdempotent
R0. Read your follows and pending registration states.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a distinct role: events, upcoming dates, documents, change feed, watchlist, follow/unfollow, calendar planning/acknowledgment, and status. The read-only public-data tools are clearly separated by resource, and the write tools are clearly separated by action. No two tools appear to do the same thing.
All tools use the same earnings_ prefix and snake_case, which keeps them readable. However, the suffix conventions are mixed: get_events is verb_noun, upcoming/documents/changes/watchlist/status are noun-oriented, and watch/unwatch/calendar_plan/calendar_ack mix action and object styles. The pattern is understandable but not consistently verb_noun.
Ten tools is a well-scoped set for an earnings-watch service. It covers reads, follows, change tracking, calendar coordination, and status without obvious redundancy. Each tool appears to earn its place.
The surface covers the core lifecycle: upcoming dates, events, documents, change feed, watchlist, follow/unfollow, calendar plan/ack, and status. Minor gaps may exist around explicit event search/filtering or calendar cancellation, but agents can likely work around them. Overall coverage is strong for the stated domain.
Maintenance
Related MCP Connectors
Economic release dates, central-bank decisions and market holidays. Read-only with a linked account.
US earnings dates, confirmed or estimated, each with its SEC EDGAR or company source URL.
Financial data and research MCP for US/CN/JP equities: filings, statements, ownership, signals.
Institutional-grade financial data: earnings, estimates, guidance, stock prices, macro indicators.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides access to financial market data via the Finnhub API, focusing on earnings calendars. It allows users to retrieve historical and upcoming earnings announcements including EPS and revenue data.MIT
- FlicenseNot gradedqualityDmaintenanceNormalizes and serves corporate events (earnings, dividends, splits, M\&A) from US, UK, Canada, and Australia via a programmatic MCP API.-
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to manage Google Calendar events, including CRUD operations, recurring events, free/busy queries, and push notifications via webhooks.ISC
- AlicenseNot gradedqualityDmaintenanceProvides macro-economic event data, earnings reports, and market overviews as MCP tools, enabling AI agents to query calendars, check event proximity, and assess trade safety.57 PyPI2MIT