Skip to main content
Glama
io.github.benjamin-di/earnings-watch

io.github.benjamin-di/earnings-watch

by benjamin-di

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 json

The 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 worker

The 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 = 20

Supported 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

earnings_upcoming

Bounded upcoming dates with timing uncertainty

earnings_get_events

Evidence, revisions and recent history

earnings_documents

Official result-document links and verification status

earnings_changes

Cursor-based public change feed

earnings_watchlist

Your follows and registration states

earnings_watch

Follow an issuer; queue registration or resolve ambiguity

earnings_unwatch

Remove a manual follow

earnings_calendar_plan

Plan optional external calendar operations

earnings_calendar_ack

Record confirmed operations from a signed plan

earnings_status

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 -d

Save 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 tools
earnings_calendar_ackEarnings Calendar AckC
Idempotent

R1. Record confirmed external operations; reject stale or altered plans.

Inputs: handle (required), results (required). Returns: object

earnings_calendar_planEarnings Calendar PlanC
Read-onlyIdempotent

R0. Plan optional Outlook operations. Apply through your external Outlook app.

Inputs: full, sink, event_ids. Returns: object

earnings_changesEarnings ChangesB
Read-onlyIdempotent

R0. Read the shared change feed; keep the returned cursor for next time.

Inputs: limit, cursor. Returns: object

earnings_documentsEarnings DocumentsC
Read-onlyIdempotent

R0. List official result-document links and their verification status.

Inputs: limit, roles, scope, since, +2 more. Returns: object

earnings_get_eventsEarnings Get EventsC
Read-onlyIdempotent

R0. Read up to 20 public events with evidence and bounded history.

Inputs: ids (required). Returns: object

earnings_statusEarnings StatusB
Read-onlyIdempotent

R0. Read catalogue counts and maintenance status without model calls.

Inputs: no named parameters. Returns: object

earnings_unwatchEarnings UnwatchC
Idempotent

R1. Remove your manual follow; public history is retained.

Inputs: ticker (required), exchange. Returns: object

earnings_upcomingEarnings UpcomingC
Read-onlyIdempotent

R0. List upcoming verified dates, including explicit timing uncertainty.

Inputs: days, limit, scope, types, +2 more. Returns: object

earnings_watchEarnings WatchC
Idempotent

R1. Follow an issuer for yourself; ambiguous tickers return candidates.

Inputs: ticker (required), isin, name, exchange. Returns: object

earnings_watchlistEarnings WatchlistB
Read-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

    B3/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Normalizes and serves corporate events (earnings, dividends, splits, M\&A) from US, UK, Canada, and Australia via a programmatic MCP API.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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 PyPI
      2
      MIT