Multi-Market Ingestion
Unified scrapers for ForexFactory, CryptoCraft, EnergyExch, and MetalsMine. Normalized schemas across fiat currencies, crypto assets, crude oil, and bullion.
Automated extraction and typed Pydantic v2 normalization across ForexFactory, CryptoCraft, EnergyExch, and MetalsMine. Terminal CLI with Rich tables, Python SDK for quant pipelines, and Model Context Protocol (MCP) server for Claude and Cursor.
Core Capabilities
Bridging raw unstructured financial calendar websites into deterministic, typed data streams.
Unified scrapers for ForexFactory, CryptoCraft, EnergyExch, and MetalsMine. Normalized schemas across fiat currencies, crypto assets, crude oil, and bullion.
Integrated cloudscraper engine transparently solves anti-bot JS challenges and emulates genuine desktop browser sessions without headless browser overhead.
Every calendar row is validated into strongly typed EconomicEvent models with aliases, field serialization, and seamless one-line conversion to Pandas DataFrames.
Turn AI systems like Claude Desktop, Cursor, and custom agentic frameworks into live market research analysts with the standard forex-mcp stdio server.
Interactive Simulation
Experience how raw financial calendar tables are mapped into structured, filterable data entities.
| Time (EST) | Asset / Currency | Event Name | Impact | Forecast | Actual | Previous |
|---|
Playground
Configure your extraction parameters and generate copy-pastable CLI commands, Python code, and MCP tool payloads in real time.
forex-scraper --source forex --format table
# Generated via builder
{}
Developer Reference
Explore setup guides, API contracts, pipeline recipes, and agent configuration templates.
The forex-scraper executable provides instant terminal queries with zero code. It supports both Rich ANSI table rendering and clean JSON output for UNIX piping.
| Flag | Type | Allowed Values | Default | Description |
|---|---|---|---|---|
--source |
String | forex, crypto, energy, metals |
forex |
Financial market calendar portal to query. |
--date |
String | YYYY-MM-DD |
Today | Specific calendar date to fetch. |
--format |
String | table, json |
json |
Output visual formatting style. |
-h, --help |
Flag | — | — | Print CLI help and argument descriptions. |
Extract only high-impact cryptocurrency events and format as a compact list:
forex-scraper --source crypto --format json | jq '.[] | select(.impact == "high") | "\(.time) [\(.currency)] \(.event) - Actual: \(.actual)"'
Import scrapers directly into algorithmic trading routines, quantitative analysis notebooks, or automated alert bots.
from datetime import datetime
import pandas as pd
from forex_pytory.core.scraper import forex_factory_scraper
# 1. Generate target URL for a specific date
now = datetime.now()
url = forex_factory_scraper.get_url(day=now.day, month=now.month, year=now.year)
# 2. Extract and validate calendar events
events = forex_factory_scraper.get_records(url)
# 3. Convert directly to Pandas DataFrame
df = pd.DataFrame([e.model_dump(by_alias=True) for e in events])
print(df[["Time", "Currency", "Event", "Impact", "Forecast", "Actual"]])
All scrapers return strongly-typed instances of EconomicEvent:
class EconomicEvent(BaseModel):
id: Optional[str] = Field(default=None, alias="ID")
time: Optional[str] = Field(default=None, alias="Time")
currency: Optional[str] = Field(default=None, alias="Currency")
event: Optional[str] = Field(default=None, alias="Event")
forecast: Optional[str] = Field(default=None, alias="Forecast")
actual: Optional[str] = Field(default=None, alias="Actual")
previous: Optional[str] = Field(default=None, alias="Previous")
impact: Optional[str] = Field(default=None, alias="Impact")
Integrate live calendar querying directly into AI coding agents and desktop assistants like Claude Desktop and Cursor. The server exposes a standard stdio JSON-RPC interface.
Add to claude_desktop_config.json:
{
"mcpServers": {
"forex-pytory": {
"command": "uvx",
"args": ["--from", "forex-pytory", "forex-mcp"]
}
}
}
fetch_economic_events| Argument | Type | Required | Description |
|---|---|---|---|
source |
String | Yes | Market calendar to query: forex, crypto, energy, or metals. |
date |
String | No | Specific date in YYYY-MM-DD format. Defaults to current date if omitted. |
Designed according to strict anti-slop, minimal overhead, and maximum resilience principles:
cloudscraper to resolve Cloudflare v1 JavaScript challenges rather than spinning up memory-heavy Chromium or Puppeteer processes.Portals & Coverage
Direct, unthrottled access across four distinct financial domains.
| Market | Source Domain | Python Scraper Module | Primary Assets Tracked |
|---|---|---|---|
| Forex | forexfactory.com |
forex_pytory.core.scraper.forex_factory_scraper |
Global fiat pairs (USD, EUR, GBP, JPY, CAD, AUD, NZD, CHF) |
| Cryptocurrency | cryptocraft.com |
forex_pytory.core.scraper.crypto_craft_scraper |
Major digital assets, difficulty adjustments, network hardforks |
| Energy | energyexch.com |
forex_pytory.core.scraper.energy_exch_scraper |
WTI Crude, Brent, Natural Gas, EIA Storage Reports |
| Precious Metals | metalsmine.com |
forex_pytory.core.scraper.metals_mine_scraper |
Gold, Silver, Platinum, COMEX Vault Deliveries |