Skip to content

Releases

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 18 Nov 05:49
0ca407a

0.2.0 (2026-11-18)

Features

  • brew: add Homebrew formula and tap installation docs (935d9a4)
  • docs: replace mkdocs with bespoke premium documentation and interactive explorer (010bb59)

Bug Fixes

  • ci: upgrade setuptools alongside pip to eliminate runner-level CVEs in security check (728c1ee)
  • security: resolve all 20 dependabot alerts by upgrading python baseline to 3.11.5+ and updating lockfile (6dff499)

v0.1.2

Choose a tag to compare

@github-actions github-actions released this 15 Nov 20:48
7c1bd71

0.1.2 (2026-11-15)

Bug Fixes

  • security: resolve dependency vulnerabilities and enforce URL scheme validation (b882323)

Documentation

  • apply well-document governance, audit fixes, and test suite (f60394a)

v0.1.1

Choose a tag to compare

@github-actions github-actions released this 18 Sep 00:05
f43816d

0.1.1 (2026-09-18)

Bug Fixes

  • update import path and constrain mcp version in pyproject.toml (6da1bca)

Documentation

  • add contributing, getting started, and CLI documentation (c482d51)
  • update installation instructions for pip and source (66206e4)

forex-pytory-v0.1.0

Choose a tag to compare

@AtaCanYmc AtaCanYmc released this 16 Jun 19:44

🎛️ • FOREX PYTORY

Advanced, Modular, and MCP-Ready Economic Events Scraper Library


CI Version License MCP Ready Python Version

Forex-Pytory is an open-source Python package that provides a robust and elegant way to scrape core economic data, news releases, and calendar events from major financial markets. Designed for modern Python ecosystems, it offers seamless integration for automated trading bots, data analysis pipelines, and even AI agents.

✨ Key Features & Capabilities

  • 🌐 Unified Multi-Source Engine:
    Stop writing different scrapers for different sites! This package natively supports ForexFactory (Forex), CryptoCraft (Crypto), EnergyExch (Energy), and MetalsMine (Precious Metals) through a single, consistent API. You get the exact same data structure regardless of which market you are querying.

  • 🛡️ Strict Type Safety with Pydantic v2:
    No more dealing with messy, unpredictable dictionaries. Every single event scraped from the web is parsed, validated, and cast into an EconomicEvent Pydantic model. This guarantees type safety, automatic data casting, and clean IDE autocompletion for fields like impact, forecast, actual, and time.

  • 💻 Powerful CLI (Command Line Interface):
    Need a quick market overview without writing code? The built-in CLI tool powered by Rich lets you pull and visualize data directly in your terminal. You can instantly view events in beautifully color-coded tables (where colors indicate market impact) or export them as raw JSON for external ingestion.

  • 🤖 MCP (Model Context Protocol) Ready:
    Welcome to the future of AI tooling. This package ships with an official MCP Server integration. This means AI Agents (like Claude 3.5 Sonnet) can securely connect to this library and invoke it as a local tool to answer your complex financial questions, summarize the daily calendar, or analyze upcoming high-impact events autonomously.


🚀 Installation

After setting up your virtual environment, you can install the project directly from the source. It is highly recommended to install with optional dependencies to unlock the CLI and MCP features:

git clone https://github.com/your-username/forex-pytory.git
cd forex-pytory
pip install -e .[mcp,cli]

(Note: Core dependencies such as pandas, beautifulsoup4, cloudscraper, pydantic, mcp, and rich will be installed automatically.)


🛠️ Usage Scenarios & Code Examples

You can use the package in 3 different ways: as a Python library, as a standalone CLI tool, or as an MCP Server connected to AI assistants.

1. Library Usage (Python API)

Import the package into your own scripts or Jupyter Notebooks to power your financial applications:

from datetime import datetime
from src.forex_pytory.core.scraper import forex_factory_scraper

# 1. Generate the target URL for today
dt = datetime.now()
url = forex_factory_scraper.get_url(day=dt.day, month=dt.month, year=dt.year, timeline="day")

# 2. Fetch and parse data (Returns a list of strictly typed Pydantic 'EconomicEvent' objects)
records = forex_factory_scraper.get_records(url)

# 3. Access attributes safely
for event in records[:3]:
    print(f"[{event.time}] {event.currency} - {event.event} (Impact: {event.impact})")

2. Command Line Interface (CLI) Usage

Upon installation, the global forex-scraper command becomes available in your terminal.

A. Modern Table View:
Use the --format table flag for a dynamic, color-coded terminal table. High-impact events are bold red, medium are yellow, etc.

forex-scraper --source forex --format table
CLI Example 1 CLI Example 2
CLI Example 3 CLI Example 4

B. JSON Format Output:
Perfect for piping into jq or integrating with other shell scripts, use --format json (which is the default behavior).

forex-scraper --source crypto --format json

3. MCP Server (Agent Integration) Usage

Connect this tool directly to your AI Assistant! By hooking the scraper up to Claude via the Model Context Protocol, Claude can fetch live calendar data to assist your analysis.

Add the following block to your claude_desktop_config.json:

{
  "mcpServers": {
    "forex-pytory": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "-m",
        "forex_pytory.mcp.server"
      ]
    }
  }
}

Restart your Claude Desktop app, and you can simply ask: "Check ForexFactory for any major Euro news today!"


⚖️ Legal and License

This project is open-sourced under the Apache License 2.0. See the LICENSE file for more details.

🚨 IMPORTANT: Please read the DISCLAIMER.md before using this software. The data provided by this tool does not constitute investment advice, and the end-user assumes all legal responsibility and risk arising from its use.

Full Changelog: https://github.com/AtaCanYmc/forex-pytory/commits/v0.1.0