# Mcp Yfinance Server (`lustrous_hologram/mcp-yfinance-server`) Actor Real-time stock API with Python, MCP server example, yfinance stock analysis dashboard - **URL**: https://apify.com/lustrous\_hologram/mcp-yfinance-server.md - **Developed by:** [Aditya Akuskar](https://apify.com/lustrous_hologram) (community) - **Categories:** Developer tools, Integrations, Agents - **Stats:** 1 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/adity-star-mcp-yfinance-server-badge.png)](https://mseep.ai/app/adity-star-mcp-yfinance-server) ## πŸ’Ή MCP YFinance Stock Server ![Python](https://img.shields.io/badge/python-3.10-blue) ![MCP](https://img.shields.io/badge/MCP-Compatible-green) ![License](https://img.shields.io/github/license/Adity-star/mcp-yfinance-server) This project sets up a **stock Price server** powered by the **Yahoo Finance (YFinance)** API and built for seamless integration with **MCP (Model Control Protocol)**. It allows AI agents or clients to: - Retrieve real-time stock data - Manage a watchlist - Perform full stock analysis - Run full technical indicators - And much more ![image](https://github.com/user-attachments/assets/b7f27442-823e-45a1-8f57-e0f6282ee36f) --- ### πŸͺ™ Start Simple: Build a Crypto Price Tracker First Before diving into the full-blown stock server, I recommend starting with this simple crypto tracker built with Python + MCP πŸ‘‡ πŸ”— GitHub Repo: https://github.com/Adity-star/mcp-crypto-server > You'll learn how to: > - Use MCP to expose crypto tools like get_price("BTC") > - Build an API with FastAPI > - Fetch real-time prices using the Alpaca API ### πŸ”— Related Projects Explore more of my work: - [GenAI-Learnings](https://github.com/Adity-star/GenAI-Learnings): A deep dive into Generative AI concepts, tools, and projects. - [LangChain-Mastery](https://github.com/Adity-star/LangChainMastery): Everything you need to master LangChain for building powerful LLM applications. - [Complete Data Science](https://github.com/Adity-star/Complete-DataScience-Guide): A deep dive into Data Science AI concepts, tools, and projects and all the material for learning and interview preparation. - [Reinforcement-Learning](https://github.com/Adity-star/Reinforcement-Learning): Hands-on experiments and theory in Reinforcement Learning. - [CompleteRAG](https://github.com/Adity-star/CompleteRAG): End-to-end implementation of Retrieval-Augmented Generation (RAG) systems. --- ### πŸ“ˆ Then Level Up: Build the yFinance Stock Server Once you're familiar with the flow, move on to this more advanced stock tracker πŸ’Ή πŸ”— GitHub Repo: [https://github.com/Adity-star/mcp-yfinance-server](https://github.com/Adity-star/mcp-yfinance-server) πŸ“ Detailed Blog: πŸ‘‰ [How I Built My Own Stock Server with Python, yFinance, and a Touch of Nerdy Ambition](https://medium.com/@aakuskar.980/how-i-built-my-own-stock-server-with-python-yfinance-and-a-touch-of-nerdy-ambition-b562dc1d7b93) > Includes: > - Watchlists > - Real-time(ish) price updates > - Technical summaries > - A full-featured dashboard > - Trend + momentum indicators > - Watchlist management --- ### πŸ“¦ Step 1: Set Up the Environment (with uv) We use **[uv](https://github.com/astral-sh/uv)** β€” a modern, ultra-fast Python package manager β€” to manage our project environment. #### πŸ› οΈ Installation & Setup Run the following commands in your terminal: ```bash ## Install uv curl -LsSf https://astral.sh/uv/install.sh | sh ## Create and navigate to your project directory mkdir mcp-yfinance-server cd mcp-yfinance-server ## Initialize a new project uv init ## Create and activate the virtual environment uv venv source .venv/bin/activate ## On Windows: .venv\Scripts\activate ```` ### πŸ“₯ Install the project Once your [pyproject.toml](https://github.com/Adity-star/mcp-yfinance-server/blob/main/pyproject.toml) is set up with dependencies, run: ```bash ## Run uv pip install -e . ``` *** ### πŸš€ Step 2: Running the MCP Server Once your environment is ready, start the stock server: ```bash uv run main.py ``` πŸ§ͺ Want a quick test first? Try checking the tools first: ```bash python run test_server_fun.py ``` πŸ“„ Curious how the full server works? Explore the source code here: πŸ”— [yf\_server.py β€Ί GitHub](https://github.com/Adity-star/mcp-yfinance-server/blob/main/source/yf_server.py) *** ## πŸ› οΈ MCP Tool Reference The server exposes many tools for AI agents and CLI users.\ Here are some important tools, check out the complete tools list [here](https://github.com/Adity-star/mcp-yfinance-server/blob/main/results/tools.md): ### πŸ“¦ Tool List | Tool Name | Description | |-------------------------------|-----------------------------------------------------------------------------| | `add_to_watchlist` | Add a stock ticker to your personal watchlist. | | `analyze_stock` |Perform a 1-month technical trend analysis (RSI, MACD, MAs).. | | `get_technical_summary` |Generate a comprehensive technical summary including indicators & signals.. | | `get_watchlist_prices` | Fetch the most recent prices for all watchlisted tickers. | | `get_trend_analysiss` | Analyze recent trend shifts, patterns, and divergences.. | | `get_stock_price` | Retrieve the current price for a given ticker symbol. | | `get_volatility_analysis` | Calculate historical volatility and ATR metrics.. | | `compare_stocks` | Compare two stock prices (useful for relative performance analysis). | > βœ… [Total: 18 powerful tools to analyze and monitor stocks with precision.](https://github.com/Adity-star/mcp-yfinance-server/blob/main/results/tools.md) ### 🧠 Use Cases These tools are ideal for: - πŸ“Š Dynamic watchlist management - πŸ” Trend and momentum detection - πŸ“ˆ Deep-dive technical analysis for investment decisions - ⚠️ Volatility-based risk assessment - πŸ€– Powering stock-focused autonomous agents or dashboards > βš™οΈ Keep this reference handy for building intelligent financial applications with the MCP server. *** ### πŸ” Step 3: Inspecting the MCP Server Easily explore and test your MCP tools using the **MCP Server Inspector**. Run the following command in your terminal: ```bash $ mcp dev source/yf_server.py ``` This launches an interactive UI to: - 🧰 View all available tools and resources - πŸ“₯ Test input/output for each tool - πŸ“‘ Monitor real-time responses from your server - ![image](https://github.com/user-attachments/assets/886182a3-e996-4713-aec6-d9ab3fac3bd9) *** ### βš™οΈ Step 4: Configure Your MCP Server To integrate your YFinance MCP server, add the following entry to your mcp.config.json file: ```json { "mcpServers": { "yfinance-price-tracker": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/YOUR/mcp-yfinance-server", "run", "main.py" ] } } } ``` > ⚠️ Replace /ABSOLUTE/PATH/TO/... with actual file paths. > πŸ’‘ Tip: Rename your server from crypto-price-tracker to yfinance-price-tracker for clarity. *** ### πŸ” Step 5: Restart Claude Desktop Restart **Claude Desktop** (or any interface that uses MCP) to reload and activate your new YFinance tools. > This ensures the updated MCP configuration is recognized and all stock tracking tools are > ready to use. *** ### βœ… Step 6: Testing the MCP Server with Claude Desktop - With everything installed and configured, you're ready to test your MCP server in **Claude Desktop**. Use these example queries to test your MCP YFinance Server in action: > "Compare the stock prices of Tesla and Apple." > β†’ πŸ”§ Uses `compare_stocks` > "Get the historical data for Tesla over the past month." > β†’ πŸ“Š Uses `get_stock_history` > "Add Apple, Tesla, and Reliance to my watchlist." > β†’ πŸ“‹ Uses `add_to_watchlist` > "Show me a chart of Apple’s stock over the last 30 days." > β†’ πŸ–ΌοΈ Claude can fetch + visualize data using your server πŸ“· Sample Chart: πŸ–Ό [view Screenshot](https://github.com/Adity-star/mcp-yfinance-server/blob/main/assets/Screenshot%20\(16\).png) 🌐 Live Claude Site: [Open Demo on Claude.site](https://claude.site/artifacts/bba1b878-de53-4988-a0b5-377f2d202b3a) πŸ§ͺ These tests ensure your MCP integration is working end-to-endβ€”from data retrieval to real-time analysis and visualization. *** ## πŸ“Š Results ### βš™οΈ Outcomes You Can Expect | Feature | Outcome | |-------------------------------------------------------------------------|-------------------------------------------------------------------------| | βœ… [**Stock Analysis**](https://claude.site/artifacts/a118060f-25ac-410b-ae37-0869dc773a98) | Analyse stock giving price, OHLC, returns, volume, insights and data. | | πŸ“ˆ [**Technical Analysis**](https://claude.site/artifacts/4642c157-8022-43b7-a2cd-472437c62e4b) | Access indicators like RSI, MACD, MA, and a complete technical summary.| | πŸ“‰ [**Volatility Reports**](https://claude.site/artifacts/08214360-f08f-48d7-9cb1-1bc7334910e9) | Analyze stock risk with ATR and volatility metrics. | | πŸ” [**Trend Analysis**](https://claude.site/artifacts/878fc17e-a845-4944-b2ee-14857da2bbfc) | Detect trend shifts and divergence using price movement analysis. | | 🧠 [**Visualisations**](https://claude.site/artifacts/4642c157-8022-43b7-a2cd-472437c62e4b) | 18+ tools ready to power AI agents or dashboards to visualise stock. | | πŸ“‹ [**Technical Charts**](https://claude.site/artifacts/559bf977-91dc-45e1-a6b7-e95a19eaaeab) | Analyse and monitor technical indicators for stocks in real-time. | | πŸ–ΌοΈ [**Visual Insights**](https://claude.site/artifacts/bba1b878-de53-4988-a0b5-377f2d202b3a) | Generate charts and visual summaries with Claude Desktop. | > πŸŽ‰ Ready to build your stock-tracking bot or intelligent financial dashboard? This project has all the core pieces. *** ### πŸ“« Feedback & Contributions Contributions are welcome! Whether you're fixing bugs, adding features, or improving documentation, your help makes this project better. #### πŸ› Reporting Issues If you encounter bugs or have suggestions, please open an issue in the [Issues section](https://github.com/Adity-star/mcp-yfinance-server/issues). Be sure to include: - βœ… Steps to reproduce (if applicable) - πŸ” Expected vs. actual behavior - πŸ“· Screenshots or error logs (if relevant) #### πŸ“¬ Submit a Pull Request Have a fix or improvement? Head over to the [Pull Requests section](https://github.com/Adity-star/mcp-yfinance-server/pulls) and submit your PR. We’ll review and merge it ASAP! *** ### πŸ’¬ Spread the Word If this project saved you from API rate limits or overpriced SaaS tools... - 🌟 **Star** the repo - 🍴 **Fork** it and build your own crypto/stock tool - πŸ“² **Tag me on X** [@AdityaAkuskar](https://x.com/AdityaAkuskar) β€” I’d love to see what you build! - πŸ”— **Connect with me on [LinkedIn](https://www.linkedin.com/in/aditya-a-27b43533a/)** *** ### πŸ“œ License [MIT Β© 2025 Ak Aditya](https://github.com/Adity-star/mcp-yfinance-server/blob/main/LICENSE). *** πŸš€ Let’s build better tools together. If you’d like a tweet thread, carousel, or launch post for this β€” I’ve got your back 😎 # Actor input Schema ## `tool` (type: `string`): The MCP tool to invoke on this run. ## `ticker` (type: `string`): Primary stock ticker symbol (e.g. AAPL, TSLA, MSFT). Required for most tools. ## `ticker2` (type: `string`): Second stock ticker for side-by-side comparison. Only used with the compare\_stocks tool. ## `watchlist` (type: `array`): List of ticker symbols to add to or retrieve from the watchlist. ## `period` (type: `string`): Time period for historical data. Used by get\_stock\_history and analyze\_stock. ## `interval` (type: `string`): Granularity of historical data points. ## Actor input object example ```json { "tool": "get_stock_price", "ticker": "AAPL", "ticker2": "TSLA", "watchlist": [ "AAPL", "TSLA", "MSFT" ], "period": "1mo", "interval": "1d" } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("lustrous_hologram/mcp-yfinance-server").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("lustrous_hologram/mcp-yfinance-server").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # πŸ“š Want to learn more πŸ“–? Go to β†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call lustrous_hologram/mcp-yfinance-server --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lustrous_hologram/mcp-yfinance-server", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Mcp Yfinance Server", "description": "Real-time stock API with Python, MCP server example, yfinance stock analysis dashboard", "version": "0.0", "x-build-id": "hoJdeItJnyumfxaVp" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lustrous_hologram~mcp-yfinance-server/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lustrous_hologram-mcp-yfinance-server", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lustrous_hologram~mcp-yfinance-server/runs": { "post": { "operationId": "runs-sync-lustrous_hologram-mcp-yfinance-server", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lustrous_hologram~mcp-yfinance-server/run-sync": { "post": { "operationId": "run-sync-lustrous_hologram-mcp-yfinance-server", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "tool" ], "properties": { "tool": { "title": "Tool Name", "enum": [ "get_stock_price", "compare_stocks", "analyze_stock", "get_technical_summary", "get_trend_analysis", "get_volatility_analysis", "add_to_watchlist", "get_watchlist_prices", "get_stock_history" ], "type": "string", "description": "The MCP tool to invoke on this run.", "default": "get_stock_price" }, "ticker": { "title": "Ticker Symbol", "type": "string", "description": "Primary stock ticker symbol (e.g. AAPL, TSLA, MSFT). Required for most tools." }, "ticker2": { "title": "Second Ticker Symbol (for compare_stocks)", "type": "string", "description": "Second stock ticker for side-by-side comparison. Only used with the compare_stocks tool." }, "watchlist": { "title": "Watchlist Tickers", "type": "array", "description": "List of ticker symbols to add to or retrieve from the watchlist.", "items": { "type": "string" } }, "period": { "title": "History Period", "enum": [ "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max" ], "type": "string", "description": "Time period for historical data. Used by get_stock_history and analyze_stock.", "default": "1mo" }, "interval": { "title": "Data Interval", "enum": [ "1m", "5m", "15m", "30m", "1h", "1d", "1wk", "1mo" ], "type": "string", "description": "Granularity of historical data points.", "default": "1d" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```