Financial Data Tools

A Python-based toolkit for fetching various financial data using the Financial Datasets API. This project provides easy access to stock information, financial metrics, insider trades, institutional ownership, and news data.

Features

• Stock Information: Basic company facts and metrics
• Financial Snapshots: Detailed financial metrics and ratios
• Insider Trades: Recent insider trading activity
• Institutional Ownership: Major institutional holders
• News Articles: Recent news articles with customizable date ranges
• Earnings Releases: Company earnings press releases (coming soon)

Prerequisites

• Python 3.12 or higher
• pip (Python package installer)
• Financial Datasets API key (get it from https://api.financialdatasets.ai/)
• Git (for installing MCP package)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/financial-data-tools.git
   cd financial-data-tools

2. Create and activate a virtual environment (recommended):

   # Windows
   python -m venv venv
   .\venv\Scripts\activate
   
   # Unix/macOS
   python -m venv venv
   source venv/bin/activate

3. Install required packages:

   # First, install the MCP package from GitHub
   pip install git+https://github.com/codeium-ai/mcp-langchain.git
   
   # Then install other dependencies
   pip install -r requirements.txt

4. Set up environment variables:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and add your API key
   # Replace 'your_api_key_here' with your actual API key

Usage

The project includes two main Python files:

stock_server.py

Contains the MCP server implementation with all the financial data tools. Each tool is implemented as a separate function that makes API calls to fetch specific types of financial data.

test_stock_server.py

A test script that demonstrates how to use all the available tools. Run it to test your setup:

python test_stock_server.py

The script will prompt you to enter a stock ticker symbol and will then fetch and display:

• Basic stock information
• Financial snapshot
• Recent insider trades
• Institutional ownership details
• Recent news articles

Available Tools

1. get_stock_info(ticker: str)

   • Fetches basic company facts and metrics
   • Returns success status and data/error message

2. get_financial_snapshot(ticker: str)

   • Retrieves detailed financial metrics
   • Returns success status and data/error message

3. get_insider_trades(ticker: str, limit: int = 10)

   • Gets recent insider trading activity
   • Configurable limit (default: 10)
   • Returns success status and data/error message

4. get_institutional_ownership(ticker: str, limit: int = 10)

   • Fetches institutional ownership details
   • Configurable limit (default: 10)
   • Returns success status and data/error message

5. get_news(ticker: str, days_back: int = 7, limit: int = 10)

   • Retrieves recent news articles
   • Configurable date range and limit
   • Returns success status and data/error message

Error Handling

All tools include comprehensive error handling:

• API key validation
• Request error handling
• Response parsing error handling
• Each response includes a 'success' boolean and either 'data' or 'error' field

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Financial Datasets API for providing the financial data
• Model Context Protocol (MCP) for the server implementation

Troubleshooting

Common Issues

1. API Key Not Set

   • Ensure you've created the .env file
   • Verify your API key is correctly set in the .env file
   • Make sure python-dotenv is installed

2. Import Errors

   • Verify all dependencies are installed: pip install -r requirements.txt
   • Ensure you're in the virtual environment

3. Request Failures

   • Check your internet connection
   • Verify your API key is valid
   • Ensure you're not exceeding API rate limits

Getting Help

If you encounter any issues:

1. Check the error message returned by the tool
2. Verify your setup against the installation steps
3. Check the API documentation for endpoint-specific issues
4. Open an issue on the GitHub repository