| Name | iso-financial-mcp JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Open-source MCP server providing comprehensive financial market data endpoints for short squeeze detection and analysis |
| upload_time | 2025-07-30 07:53:18 |
| maintainer | None |
| docs_url | None |
| author | Niels-8 |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2024 Trading Agents Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
finance
market-data
mcp
model-context-protocol
options
short-squeeze
stocks
trading
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# IsoFinancial-MCP
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://badge.fury.io/py/iso-financial-mcp)
An open-source MCP (Model Context Protocol) server providing comprehensive financial market data endpoints for short squeeze detection and analysis. Uses free financial data APIs including Yahoo Finance and other public sources.
## 🚀 Features
- **Real-time Market Data**: Live stock prices, volume, and market statistics
- **Financial Statements**: Balance sheets, income statements, and cash flow data
- **Options Analysis**: Option chains, expiration dates, and options data
- **Corporate Actions**: Dividends, stock splits, and earnings calendars
- **Company Information**: Company profiles, major holders, and institutional investors
- **Analyst Recommendations**: Professional analyst ratings and recommendations
## 📋 Requirements
- Python 3.10+
- uv (recommended package manager)
- Internet connection for API access
## 🔧 Installation
### Using uv (Recommended)
```bash
uv add iso-financial-mcp
```
### Using pip
```bash
pip install iso-financial-mcp
```
## 🚀 Quick Start
### As MCP Server (for AI agents)
```python
from fastmcp.agent import StdioServerParams, mcp_server_tools
# Configure the MCP server
finance_server_params = StdioServerParams(
command="python",
args=["-m", "server"],
cwd="./IsoFinancial-MCP"
)
# Get available tools
finance_tools = await mcp_server_tools(finance_server_params)
```
### As HTTP Server
```bash
# Start HTTP server
python main.py --mode http --port 8000
# Or with uvicorn directly
uvicorn server:app --host 0.0.0.0 --port 8000
```
## 📊 Available Endpoints
### Market Data
- `get_info(ticker)` - Company profile and basic information
- `get_historical_prices(ticker, period, interval)` - Historical price data
### Financial Data
- `get_balance_sheet(ticker, freq)` - Balance sheet data
- `get_financials(ticker, freq)` - Income statement data
- `get_cash_flow(ticker, freq)` - Cash flow statement
### Options Analysis
- `get_options_expirations(ticker)` - Available expiration dates
- `get_option_chain(ticker, expiration_date)` - Complete option chain
### Corporate Actions
- `get_actions(ticker)` - Dividends and stock splits
- `get_earnings_dates(ticker)` - Earnings calendar
### Company Information
- `get_major_holders(ticker)` - Major shareholders
- `get_institutional_holders(ticker)` - Institutional holdings
- `get_recommendations(ticker)` - Analyst recommendations
- `get_isin(ticker)` - ISIN code
### Short Interest Analysis (COMING SOON)
- `get_short_interest(ticker)` - Current short interest data
- `get_short_interest_history(ticker, lookback)` - Historical short interest
- `get_days_to_cover(ticker)` - Days to cover calculation
- `get_cost_to_borrow(ticker)` - Current borrowing costs
### Volume Analysis (COMING SOON)
- `get_short_volume_daily(ticker, date)` - Daily short volume (FINRA)
- `get_short_volume_intraday(ticker, date)` - Intraday short volume
- `get_short_exempt_volume_daily(ticker, date)` - Short exempt volume
### Dark Pool & FTD Data (COMING SOON)
- `get_dark_pool_volume_daily(ticker, date)` - Daily dark pool volume
- `get_fail_to_deliver(ticker, from_date, to_date)` - Fail-to-deliver data
### Advanced Options Analysis (COMING SOON)
- `get_option_oi_by_strike(ticker, expiry)` - Open interest by strike
- `get_gamma_exposure(ticker, date)` - Gamma exposure calculation
- `get_max_pain(ticker, expiry)` - Max pain calculation
### Screening Tools (COMING SOON)
- `get_high_short_interest_tickers(threshold, limit)` - High SI tickers
- `get_latest_price(ticker)` - Current stock price
- `get_free_float(ticker)` - Free float data
- `get_company_profile(ticker)` - Detailed company profile
- `get_earnings_calendar(ticker, window)` - Earnings calendar
- `ping()` - Connectivity test
## 📖 Usage Examples
### Basic Market Data
```python
# Get company information
info = await get_info("AAPL")
# Get historical prices
prices = await get_historical_prices("TSLA", period="6mo", interval="1d")
# Get current price
price = await get_latest_price("GME")
```
### Financial Analysis
```python
# Get balance sheet
balance = await get_balance_sheet("AAPL", freq="yearly")
# Get income statement
income = await get_financials("TSLA", freq="quarterly")
# Get cash flow
cashflow = await get_cash_flow("MSFT", freq="yearly")
```
### Options Analysis
```python
# Get option expirations
expirations = await get_options_expirations("SPY")
# Get option chain
chain = await get_option_chain("SPY", "2024-01-19")
```
### Corporate Actions
```python
# Get dividends and splits
actions = await get_actions("AAPL")
# Get earnings dates
earnings = await get_earnings_dates("TSLA")
```
### Company Information
```python
# Get major shareholders
holders = await get_major_holders("GME")
# Get institutional investors
institutional = await get_institutional_holders("AAPL")
# Get analyst recommendations
recommendations = await get_recommendations("TSLA")
```
## 🔧 Configuration
The server uses free APIs by default (Yahoo Finance). No API keys are required for basic functionality.
```bash
# Copy environment template (optional)
cp .env.example .env
# No API keys needed for current features
# All data is sourced from Yahoo Finance (free)
```
## 🧪 Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=datasources
```
## 📦 Development
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Format code
black .
ruff check .
# Type checking
mypy .
```
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Yahoo Finance](https://finance.yahoo.com/) for market data
- [FastMCP](https://github.com/fastmcp/fastmcp) for the MCP framework
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/Niels-8/isofinancial-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Niels-8/isofinancial-mcp/discussions)
---
**Disclaimer**: This software is for educational and research purposes only. Always verify data independently before making investment decisions.
Raw data
{
"_id": null,
"home_page": null,
"name": "iso-financial-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "finance, market-data, mcp, model-context-protocol, options, short-squeeze, stocks, trading",
"author": "Niels-8",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c3/64/db1feb2d5c6c3db5f15beb604bafd9e5988504a5e8a510d5f1794177a0b8/iso_financial_mcp-0.1.1.tar.gz",
"platform": null,
"description": "# IsoFinancial-MCP\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://badge.fury.io/py/iso-financial-mcp)\n\nAn open-source MCP (Model Context Protocol) server providing comprehensive financial market data endpoints for short squeeze detection and analysis. Uses free financial data APIs including Yahoo Finance and other public sources.\n\n## \ud83d\ude80 Features\n\n- **Real-time Market Data**: Live stock prices, volume, and market statistics\n- **Financial Statements**: Balance sheets, income statements, and cash flow data\n- **Options Analysis**: Option chains, expiration dates, and options data\n- **Corporate Actions**: Dividends, stock splits, and earnings calendars\n- **Company Information**: Company profiles, major holders, and institutional investors\n- **Analyst Recommendations**: Professional analyst ratings and recommendations\n\n## \ud83d\udccb Requirements\n\n- Python 3.10+\n- uv (recommended package manager)\n- Internet connection for API access\n\n## \ud83d\udd27 Installation\n\n### Using uv (Recommended)\n\n```bash\nuv add iso-financial-mcp\n```\n\n### Using pip\n\n```bash\npip install iso-financial-mcp\n```\n\n## \ud83d\ude80 Quick Start\n\n### As MCP Server (for AI agents)\n\n```python\nfrom fastmcp.agent import StdioServerParams, mcp_server_tools\n\n# Configure the MCP server\nfinance_server_params = StdioServerParams(\n command=\"python\",\n args=[\"-m\", \"server\"],\n cwd=\"./IsoFinancial-MCP\"\n)\n\n# Get available tools\nfinance_tools = await mcp_server_tools(finance_server_params)\n```\n\n### As HTTP Server\n\n```bash\n# Start HTTP server\npython main.py --mode http --port 8000\n\n# Or with uvicorn directly\nuvicorn server:app --host 0.0.0.0 --port 8000\n```\n\n## \ud83d\udcca Available Endpoints\n\n### Market Data\n- `get_info(ticker)` - Company profile and basic information\n- `get_historical_prices(ticker, period, interval)` - Historical price data\n\n### Financial Data\n- `get_balance_sheet(ticker, freq)` - Balance sheet data\n- `get_financials(ticker, freq)` - Income statement data\n- `get_cash_flow(ticker, freq)` - Cash flow statement\n\n### Options Analysis\n- `get_options_expirations(ticker)` - Available expiration dates\n- `get_option_chain(ticker, expiration_date)` - Complete option chain\n\n### Corporate Actions\n- `get_actions(ticker)` - Dividends and stock splits\n- `get_earnings_dates(ticker)` - Earnings calendar\n\n### Company Information\n- `get_major_holders(ticker)` - Major shareholders\n- `get_institutional_holders(ticker)` - Institutional holdings\n- `get_recommendations(ticker)` - Analyst recommendations\n- `get_isin(ticker)` - ISIN code\n\n### Short Interest Analysis (COMING SOON)\n- `get_short_interest(ticker)` - Current short interest data\n- `get_short_interest_history(ticker, lookback)` - Historical short interest\n- `get_days_to_cover(ticker)` - Days to cover calculation\n- `get_cost_to_borrow(ticker)` - Current borrowing costs\n\n### Volume Analysis (COMING SOON)\n- `get_short_volume_daily(ticker, date)` - Daily short volume (FINRA)\n- `get_short_volume_intraday(ticker, date)` - Intraday short volume\n- `get_short_exempt_volume_daily(ticker, date)` - Short exempt volume\n\n### Dark Pool & FTD Data (COMING SOON)\n- `get_dark_pool_volume_daily(ticker, date)` - Daily dark pool volume\n- `get_fail_to_deliver(ticker, from_date, to_date)` - Fail-to-deliver data\n\n### Advanced Options Analysis (COMING SOON)\n- `get_option_oi_by_strike(ticker, expiry)` - Open interest by strike\n- `get_gamma_exposure(ticker, date)` - Gamma exposure calculation\n- `get_max_pain(ticker, expiry)` - Max pain calculation\n\n### Screening Tools (COMING SOON)\n- `get_high_short_interest_tickers(threshold, limit)` - High SI tickers\n- `get_latest_price(ticker)` - Current stock price\n- `get_free_float(ticker)` - Free float data\n- `get_company_profile(ticker)` - Detailed company profile\n- `get_earnings_calendar(ticker, window)` - Earnings calendar\n- `ping()` - Connectivity test\n\n## \ud83d\udcd6 Usage Examples\n\n### Basic Market Data\n\n```python\n# Get company information\ninfo = await get_info(\"AAPL\")\n\n# Get historical prices\nprices = await get_historical_prices(\"TSLA\", period=\"6mo\", interval=\"1d\")\n\n# Get current price\nprice = await get_latest_price(\"GME\")\n```\n\n### Financial Analysis\n\n```python\n# Get balance sheet\nbalance = await get_balance_sheet(\"AAPL\", freq=\"yearly\")\n\n# Get income statement\nincome = await get_financials(\"TSLA\", freq=\"quarterly\")\n\n# Get cash flow\ncashflow = await get_cash_flow(\"MSFT\", freq=\"yearly\")\n```\n\n### Options Analysis\n\n```python\n# Get option expirations\nexpirations = await get_options_expirations(\"SPY\")\n\n# Get option chain\nchain = await get_option_chain(\"SPY\", \"2024-01-19\")\n```\n\n### Corporate Actions\n\n```python\n# Get dividends and splits\nactions = await get_actions(\"AAPL\")\n\n# Get earnings dates\nearnings = await get_earnings_dates(\"TSLA\")\n```\n\n### Company Information\n\n```python\n# Get major shareholders\nholders = await get_major_holders(\"GME\")\n\n# Get institutional investors\ninstitutional = await get_institutional_holders(\"AAPL\")\n\n# Get analyst recommendations\nrecommendations = await get_recommendations(\"TSLA\")\n```\n\n## \ud83d\udd27 Configuration\n\nThe server uses free APIs by default (Yahoo Finance). No API keys are required for basic functionality.\n\n```bash\n# Copy environment template (optional)\ncp .env.example .env\n\n# No API keys needed for current features\n# All data is sourced from Yahoo Finance (free)\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=datasources\n```\n\n## \ud83d\udce6 Development\n\n```bash\n# Install development dependencies\nuv pip install -e \".[dev]\"\n\n# Format code\nblack .\nruff check .\n\n# Type checking\nmypy .\n```\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [Yahoo Finance](https://finance.yahoo.com/) for market data\n- [FastMCP](https://github.com/fastmcp/fastmcp) for the MCP framework\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/Niels-8/isofinancial-mcp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/Niels-8/isofinancial-mcp/discussions)\n\n---\n\n**Disclaimer**: This software is for educational and research purposes only. Always verify data independently before making investment decisions. ",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Trading Agents Team\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE. ",
"summary": "Open-source MCP server providing comprehensive financial market data endpoints for short squeeze detection and analysis",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/Niels-8/isofinancial-mcp/issues",
"Documentation": "https://github.com/Niels-8/isofinancial-mcp#readme",
"Homepage": "https://github.com/Niels-8/isofinancial-mcp",
"Issues": "https://github.com/Niels-8/isofinancial-mcp/issues",
"Repository": "https://github.com/Niels-8/isofinancial-mcp"
},
"split_keywords": [
"finance",
" market-data",
" mcp",
" model-context-protocol",
" options",
" short-squeeze",
" stocks",
" trading"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3fef03be4ca8299f09e2ddec093dbe85c74e46c75bfa96f5678cf33ef66e8d3b",
"md5": "29eaade0af28532cc832fabf14dc43da",
"sha256": "66c6631e0123c4602c190a2632cc97260698d0647202aa049739e0ee7b3cf979"
},
"downloads": -1,
"filename": "iso_financial_mcp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29eaade0af28532cc832fabf14dc43da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11625,
"upload_time": "2025-07-30T07:53:17",
"upload_time_iso_8601": "2025-07-30T07:53:17.027474Z",
"url": "https://files.pythonhosted.org/packages/3f/ef/03be4ca8299f09e2ddec093dbe85c74e46c75bfa96f5678cf33ef66e8d3b/iso_financial_mcp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c364db1feb2d5c6c3db5f15beb604bafd9e5988504a5e8a510d5f1794177a0b8",
"md5": "9d9cbf79bdd375ee489a5a3e146c7c2b",
"sha256": "0b4948992bc44a72be4d01cdfd8138c5e2271b5dc27e88c7f4d137979231f858"
},
"downloads": -1,
"filename": "iso_financial_mcp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9d9cbf79bdd375ee489a5a3e146c7c2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 152597,
"upload_time": "2025-07-30T07:53:18",
"upload_time_iso_8601": "2025-07-30T07:53:18.775856Z",
"url": "https://files.pythonhosted.org/packages/c3/64/db1feb2d5c6c3db5f15beb604bafd9e5988504a5e8a510d5f1794177a0b8/iso_financial_mcp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 07:53:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Niels-8",
"github_project": "isofinancial-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iso-financial-mcp"
}
