# finance-tools-mcp: A Financial Analysis MCP Server
> https://github.com/VoxLink-org/finance-tools-mcp
## Overview
The **finance-tools-mcp** is a Model Context Protocol (MCP) server designed to provide comprehensive financial insights and analysis capabilities to Large Language Models (LLMs). Modified from [investor-agent](https://github.com/ferdousbhai/investor-agent), it integrates with various data sources and analytical libraries to offer a suite of tools for detailed financial research and analysis.
<a href="https://glama.ai/mcp/servers/@VoxLink-org/finance-tools-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@VoxLink-org/finance-tools-mcp/badge" alt="Finance Tools MCP server" />
</a>
## Tools Offered
The server exposes a variety of tools via the MCP, allowing connected clients (like LLMs) to access specific financial data and perform analyses:
* **Ticker Data Tools:**
* `get_ticker_data`: Provides a comprehensive report for a given ticker, including overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.
* `get_options`: Retrieves options data with the highest open interest for a ticker, with filtering options for date range, strike price, and option type (Calls/Puts).
* `get_price_history`: Fetches historical price data digest for a specified period, including OHLCV samples, Technical Indicators, Risk Metrics, and other quantitative analysis.
* `get_financial_statements`: Accesses financial statements (income, balance, cash flow) for a ticker, available quarterly or annually.
* `get_institutional_holders`: Lists major institutional and mutual fund holders for a ticker.
* `get_earnings_history`: Provides earnings history with estimates and surprises for a ticker.
* `get_insider_trades`: Retrieves recent insider trading activity for a ticker.
* `get_ticker_news_tool`: Fetches the latest Yahoo Finance news for a specific ticker.
* **Fear & Greed Index Tools:**
* `get_current_fng_tool`: Gets the current CNN Fear & Greed Index score and rating.
* `get_historical_fng_tool`: Retrieves historical CNN Fear & Greed Index data for a specified number of days.
* `analyze_fng_trend`: Analyzes trends in the CNN Fear & Greed Index over a specified period.
* **Calculation Tools:**
* `calculate`: Evaluates mathematical expressions using Python's math syntax and NumPy.
* **Macro Data Tools:**
* `get_current_time`: Provides the current time.
* `get_fred_series`: Retrieves data for a specific FRED series ID.
* `search_fred_series`: Searches for popular FRED series by keyword.
* `cnbc_news_feed`: Fetches the latest breaking world news from CNBC, BBC, and SCMP.
## Time Series Data Processing and Optimization
The server utilizes `yfinance` to retrieve historical price data (OHLCV - Open, High, Low, Close, Volume) for tickers. This raw data undergoes significant processing and analysis to provide valuable insights, particularly optimized for consumption by LLMs.
Key aspects of the time series data handling include:
* **Comprehensive Analysis:** The data is analyzed using libraries like `ta-lib-python` to calculate a wide range of technical indicators. Additionally, custom functions compute basic statistics, risk metrics, recognize common chart patterns, and calculate Fibonacci retracement levels.
* **Structured Digest:** The results of this analysis are compiled into a structured digest format (`generate_time_series_digest_for_LLM`) that is easy for LLMs to parse and understand, including sections for statistics, summary, technical indicators, risk metrics, patterns, Fibonacci levels, and a data sample.
* **Smart Sampling for LLMs:** To provide LLMs with a representative view of historical data without overwhelming the context window, a "smart sampling" strategy is employed (`get_latest_data_sample`). This method samples the data with varying resolutions:
* **High Resolution:** Recent data points are included daily.
* **Medium Resolution:** Intermediate data points are sampled weekly.
* **Low Resolution:** Older data points are sampled monthly.
This hybrid approach ensures that the LLM receives detailed information about recent price movements while still having context about longer-term trends, all within a manageable number of data points.
This optimized processing and presentation of time series data allows LLMs to quickly grasp key trends, indicators, and patterns, facilitating more informed financial analysis.
## Sample Report
## Prerequisites
* **Python:** 3.10 or higher
* **Package Manager:** [uv](https://docs.astral.sh/uv/)
## Installation
First, install **uv** if you haven't already:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then, you can run the **finance-tools-mcp** MCP server using `uvx`:
```bash
uvx finance-tools-mcp
```
If you want to use your own FRED API key, you can set it as an environment variable:
```bash
FRED_API_KEY=YOUR_API_KEY uvx finance-tools-mcp
```
You can also run the server using Server-Sent Events (SSE) transport:
```bash
uvx finance-tools-mcp --transport sse
```
Or with the FRED API key and SSE transport:
```bash
FRED_API_KEY=YOUR_API_KEY uvx finance-tools-mcp --transport sse
```
## Usage with MCP Clients
To integrate **finance-tools-mcp** with an MCP client (for example, Claude Desktop), add the following configuration to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"investor": {
"command": "path/to/uvx/command/uvx",
"args": ["finance-tools-mcp"],
}
}
}
```
## Debugging
You can leverage the MCP inspector to debug the server:
```bash
npx @modelcontextprotocol/inspector uvx finance-tools-mcp
```
or
```bash
npx @modelcontextprotocol/inspector uv --directory ./ run finance-tools-mcp
```
For log monitoring, check the following directories:
* macOS: `~/Library/Logs/Claude/mcp*.log`
* Windows: `%APPDATA%\Claude\logs\mcp*.log`
## Development
For local development and testing:
1. Use the MCP inspector as described in the [Debugging](#debugging) section.
2. Test using Claude Desktop with this configuration:
```json
{
"mcpServers": {
"investor": {
"command": "path/to/uv/command/uv",
"args": ["--directory", "path/to/finance-tools-mcp", "run", "finance-tools-mcp"],
}
}
}
```
## License
This MCP server is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Samples
- [carvana_analysis.md](reports/carvana_analysis.md)
- [palantir_analysis.md](reports/palantir_analysis.md)
- [pdd_analysis_20250503.md](reports/pdd_analysis_20250503.md)
- [meli_se_shop_comparison_20250504.md](reports/meli_se_shop_comparison_20250504.md)
- [GLD_analysis_20250508.md](reports/GLD_analysis_20250508.md)
## Todo
- [ ] Add supporting levels and resistance levels for stocks
- [x] Add Fibonacci retracement levels for stocks
- [ ] Add moving average confluence levels for stocks
- [ ] Add option model for prediction
- [ ] Add predictive model by using finance sheets and other features
## Data Sources
- fintel.com
- investing.com
- yahoo.com
- fred.stlouisfed.org
- cnn cnbc and reddit
Raw data
{
"_id": null,
"home_page": null,
"name": "finance-tools-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, broker, finance, investment, mcp, model context protocol, robinhood, trading, wallstreetbets",
"author": null,
"author_email": "wanghsinche <wanghsinche@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/30/23/b438dcc351b668169d0910a6a68a97424d074bc4a3c94eb6d66e2e61ca98/finance_tools_mcp-0.1.3.tar.gz",
"platform": null,
"description": "# finance-tools-mcp: A Financial Analysis MCP Server\n> https://github.com/VoxLink-org/finance-tools-mcp\n\n## Overview\n\nThe **finance-tools-mcp** is a Model Context Protocol (MCP) server designed to provide comprehensive financial insights and analysis capabilities to Large Language Models (LLMs). Modified from [investor-agent](https://github.com/ferdousbhai/investor-agent), it integrates with various data sources and analytical libraries to offer a suite of tools for detailed financial research and analysis.\n\n<a href=\"https://glama.ai/mcp/servers/@VoxLink-org/finance-tools-mcp\">\n <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@VoxLink-org/finance-tools-mcp/badge\" alt=\"Finance Tools MCP server\" />\n</a>\n\n\n## Tools Offered\n\nThe server exposes a variety of tools via the MCP, allowing connected clients (like LLMs) to access specific financial data and perform analyses:\n\n* **Ticker Data Tools:**\n * `get_ticker_data`: Provides a comprehensive report for a given ticker, including overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.\n * `get_options`: Retrieves options data with the highest open interest for a ticker, with filtering options for date range, strike price, and option type (Calls/Puts).\n * `get_price_history`: Fetches historical price data digest for a specified period, including OHLCV samples, Technical Indicators, Risk Metrics, and other quantitative analysis.\n * `get_financial_statements`: Accesses financial statements (income, balance, cash flow) for a ticker, available quarterly or annually.\n * `get_institutional_holders`: Lists major institutional and mutual fund holders for a ticker.\n * `get_earnings_history`: Provides earnings history with estimates and surprises for a ticker.\n * `get_insider_trades`: Retrieves recent insider trading activity for a ticker.\n * `get_ticker_news_tool`: Fetches the latest Yahoo Finance news for a specific ticker.\n\n* **Fear & Greed Index Tools:**\n * `get_current_fng_tool`: Gets the current CNN Fear & Greed Index score and rating.\n * `get_historical_fng_tool`: Retrieves historical CNN Fear & Greed Index data for a specified number of days.\n * `analyze_fng_trend`: Analyzes trends in the CNN Fear & Greed Index over a specified period.\n\n* **Calculation Tools:**\n * `calculate`: Evaluates mathematical expressions using Python's math syntax and NumPy.\n\n* **Macro Data Tools:**\n * `get_current_time`: Provides the current time.\n * `get_fred_series`: Retrieves data for a specific FRED series ID.\n * `search_fred_series`: Searches for popular FRED series by keyword.\n * `cnbc_news_feed`: Fetches the latest breaking world news from CNBC, BBC, and SCMP.\n\n## Time Series Data Processing and Optimization\n\nThe server utilizes `yfinance` to retrieve historical price data (OHLCV - Open, High, Low, Close, Volume) for tickers. This raw data undergoes significant processing and analysis to provide valuable insights, particularly optimized for consumption by LLMs.\n\nKey aspects of the time series data handling include:\n\n* **Comprehensive Analysis:** The data is analyzed using libraries like `ta-lib-python` to calculate a wide range of technical indicators. Additionally, custom functions compute basic statistics, risk metrics, recognize common chart patterns, and calculate Fibonacci retracement levels.\n* **Structured Digest:** The results of this analysis are compiled into a structured digest format (`generate_time_series_digest_for_LLM`) that is easy for LLMs to parse and understand, including sections for statistics, summary, technical indicators, risk metrics, patterns, Fibonacci levels, and a data sample.\n* **Smart Sampling for LLMs:** To provide LLMs with a representative view of historical data without overwhelming the context window, a \"smart sampling\" strategy is employed (`get_latest_data_sample`). This method samples the data with varying resolutions:\n * **High Resolution:** Recent data points are included daily.\n * **Medium Resolution:** Intermediate data points are sampled weekly.\n * **Low Resolution:** Older data points are sampled monthly.\n This hybrid approach ensures that the LLM receives detailed information about recent price movements while still having context about longer-term trends, all within a manageable number of data points.\n\nThis optimized processing and presentation of time series data allows LLMs to quickly grasp key trends, indicators, and patterns, facilitating more informed financial analysis.\n\n## Sample Report\n\n\n## Prerequisites\n\n* **Python:** 3.10 or higher\n* **Package Manager:** [uv](https://docs.astral.sh/uv/)\n\n## Installation\n\nFirst, install **uv** if you haven't already:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nThen, you can run the **finance-tools-mcp** MCP server using `uvx`:\n\n```bash\nuvx finance-tools-mcp\n```\n\nIf you want to use your own FRED API key, you can set it as an environment variable:\n\n```bash\nFRED_API_KEY=YOUR_API_KEY uvx finance-tools-mcp\n```\n\nYou can also run the server using Server-Sent Events (SSE) transport:\n\n```bash\nuvx finance-tools-mcp --transport sse\n```\n\nOr with the FRED API key and SSE transport:\n\n```bash\nFRED_API_KEY=YOUR_API_KEY uvx finance-tools-mcp --transport sse\n```\n\n## Usage with MCP Clients\n\nTo integrate **finance-tools-mcp** with an MCP client (for example, Claude Desktop), add the following configuration to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"investor\": {\n \"command\": \"path/to/uvx/command/uvx\",\n \"args\": [\"finance-tools-mcp\"],\n }\n }\n}\n```\n\n## Debugging\n\nYou can leverage the MCP inspector to debug the server:\n\n```bash\nnpx @modelcontextprotocol/inspector uvx finance-tools-mcp\n```\n\nor\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory ./ run finance-tools-mcp\n```\n\nFor log monitoring, check the following directories:\n\n* macOS: `~/Library/Logs/Claude/mcp*.log`\n* Windows: `%APPDATA%\\Claude\\logs\\mcp*.log`\n\n## Development\n\nFor local development and testing:\n\n1. Use the MCP inspector as described in the [Debugging](#debugging) section.\n2. Test using Claude Desktop with this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"investor\": {\n \"command\": \"path/to/uv/command/uv\",\n \"args\": [\"--directory\", \"path/to/finance-tools-mcp\", \"run\", \"finance-tools-mcp\"],\n }\n }\n}\n```\n\n## License\n\nThis MCP server is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Samples\n- [carvana_analysis.md](reports/carvana_analysis.md)\n- [palantir_analysis.md](reports/palantir_analysis.md)\n- [pdd_analysis_20250503.md](reports/pdd_analysis_20250503.md)\n- [meli_se_shop_comparison_20250504.md](reports/meli_se_shop_comparison_20250504.md)\n- [GLD_analysis_20250508.md](reports/GLD_analysis_20250508.md)\n\n## Todo\n- [ ] Add supporting levels and resistance levels for stocks\n- [x] Add Fibonacci retracement levels for stocks\n- [ ] Add moving average confluence levels for stocks\n- [ ] Add option model for prediction\n- [ ] Add predictive model by using finance sheets and other features\n \n## Data Sources\n- fintel.com\n- investing.com\n- yahoo.com\n- fred.stlouisfed.org\n- cnn cnbc and reddit\n",
"bugtrack_url": null,
"license": null,
"summary": "A Model Context Protocol server for a collection of financial tools, https://github.com/VoxLink-org/finance-tools-mcp, modified from [investor-agent](https://github.com/ferdousbhai/investor-agent)",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [
"agent",
" broker",
" finance",
" investment",
" mcp",
" model context protocol",
" robinhood",
" trading",
" wallstreetbets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5fbff298488bd94d4742ce9851c51c6fb69605d7abbfebb5a937357aa3530343",
"md5": "a8b42f28d923cbd05bff43ce214ce070",
"sha256": "c2f9474c32ea0242bc7e3376e58f8f5cc8220d9f35bb6c42474c75968375bf78"
},
"downloads": -1,
"filename": "finance_tools_mcp-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8b42f28d923cbd05bff43ce214ce070",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 71356,
"upload_time": "2025-08-01T16:34:02",
"upload_time_iso_8601": "2025-08-01T16:34:02.931605Z",
"url": "https://files.pythonhosted.org/packages/5f/bf/f298488bd94d4742ce9851c51c6fb69605d7abbfebb5a937357aa3530343/finance_tools_mcp-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3023b438dcc351b668169d0910a6a68a97424d074bc4a3c94eb6d66e2e61ca98",
"md5": "59adfd27709a11d900455ccbafd120e9",
"sha256": "9f8a558e7a8684c75fd4fc54bdb7f1c7e6ca5d14ca3bb3607334ea6028f56e91"
},
"downloads": -1,
"filename": "finance_tools_mcp-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "59adfd27709a11d900455ccbafd120e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 669660,
"upload_time": "2025-08-01T16:34:04",
"upload_time_iso_8601": "2025-08-01T16:34:04.375260Z",
"url": "https://files.pythonhosted.org/packages/30/23/b438dcc351b668169d0910a6a68a97424d074bc4a3c94eb6d66e2e61ca98/finance_tools_mcp-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 16:34:04",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "finance-tools-mcp"
}
JSON