Spaces:
Sleeping
Sleeping
| title: Market and Stock MCP | |
| emoji: 📈 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: gradio | |
| sdk_version: 4.44.1 | |
| app_file: app.py | |
| pinned: false | |
| license: mit | |
| tags: | |
| - mcp | |
| - building-mcp-track-consumer | |
| - model-context-protocol | |
| - fastmcp | |
| - gradio | |
| # 📈 Finnhub Market Info MCP Server | |
| An MCP (Model Context Protocol) server that provides access to real-time stock market data and news via the Finnhub API. Built with fastMCP and Gradio. | |
| ## 🌟 Features | |
| This MCP server provides three powerful tools: | |
| 1. **Quote Tool** - Get real-time quote data for US stocks | |
| - Current price, change, percent change | |
| - High, low, open, previous close | |
| - Real-time timestamp | |
| 2. **Market News Tool** - Get latest market news | |
| - General market news | |
| - Forex, crypto, merger news categories | |
| - Latest headlines and summaries | |
| 3. **Company News Tool** - Get company-specific news | |
| - News by stock symbol | |
| - Customizable date ranges | |
| - Only for North American companies | |
| ## 🚀 Quick Start | |
| ### For Web UI Testing | |
| 1. Visit the [Hugging Face Space](https://huggingface.co/spaces/JC321/MarketandStockMCP) | |
| 2. Go to the **Configuration** tab | |
| 3. Enter your Finnhub API key (get one free at [finnhub.io](https://finnhub.io/register)) | |
| 4. Test the tools in their respective tabs | |
| ### For MCP Client Integration | |
| **Standard MCP Protocol (JSON-RPC over SSE):** | |
| This server implements the standard Model Context Protocol using JSON-RPC over Server-Sent Events (SSE). | |
| **Method 1: Using the standalone MCP server (Recommended)** | |
| For pure MCP client connections: | |
| ```bash | |
| # Run the standalone MCP server | |
| python mcp_server.py | |
| ``` | |
| Then configure your MCP client: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "finnhub": { | |
| "command": "python", | |
| "args": ["path/to/mcp_server.py"], | |
| "env": { | |
| "FINNHUB_API_KEY": "your_api_key_here" | |
| } | |
| } | |
| } | |
| } | |
| ``` | |
| **Method 2: Using app.py with --mcp flag** | |
| Alternatively, you can use the main app.py file: | |
| ```bash | |
| # Run the MCP server mode | |
| python app.py --mcp | |
| ``` | |
| Then configure your MCP client: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "finnhub": { | |
| "command": "python", | |
| "args": ["path/to/app.py", "--mcp"], | |
| "env": { | |
| "FINNHUB_API_KEY": "your_api_key_here" | |
| } | |
| } | |
| } | |
| } | |
| ``` | |
| **Note:** Both methods use the standard MCP protocol (JSON-RPC over SSE) and are fully compatible with all MCP clients. | |
| ## 📚 Detailed MCP Integration Guide | |
| ### Step-by-Step Setup | |
| #### 1️⃣ Prerequisites | |
| - Python 3.8 or higher | |
| - Finnhub API key (free at [finnhub.io/register](https://finnhub.io/register)) | |
| - An MCP-compatible client (Claude Desktop, Cursor, etc.) | |
| #### 2️⃣ Clone the Repository | |
| ```bash | |
| git clone https://huggingface.co/spaces/JC321/MarketandStockMCP | |
| cd MarketandStockMCP | |
| ``` | |
| #### 3️⃣ Install Dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| #### 4️⃣ Configure API Key | |
| **Option A: Environment Variable** | |
| ```bash | |
| # Linux/macOS | |
| export FINNHUB_API_KEY="your_api_key_here" | |
| # Windows CMD | |
| set FINNHUB_API_KEY=your_api_key_here | |
| # Windows PowerShell | |
| $env:FINNHUB_API_KEY="your_api_key_here" | |
| ``` | |
| **Option B: .env File** | |
| ```bash | |
| # Create .env file | |
| echo "FINNHUB_API_KEY=your_api_key_here" > .env | |
| ``` | |
| #### 5️⃣ Run the MCP Server | |
| **Recommended: Use the standalone MCP server** | |
| ```bash | |
| python mcp_server.py | |
| ``` | |
| **Or use app.py with --mcp flag:** | |
| ```bash | |
| python app.py --mcp | |
| ``` | |
| You should see: | |
| ``` | |
| ✅ API Key loaded from environment variable | |
| ▶️ Starting Finnhub MCP Server (JSON-RPC over SSE)... | |
| 📡 Server name: finnhub-market-info | |
| 🔧 Protocol: Model Context Protocol (MCP) | |
| 🌐 Transport: SSE (Server-Sent Events) | |
| ``` | |
| #### 6️⃣ Configure Your MCP Client | |
| **For Claude Desktop:** | |
| Edit the configuration file: | |
| - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` | |
| - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` | |
| Add this configuration: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "finnhub": { | |
| "command": "python", | |
| "args": ["C:\\path\\to\\MarketandStockMCP\\mcp_server.py"], | |
| "env": { | |
| "FINNHUB_API_KEY": "your_finnhub_api_key_here" | |
| } | |
| } | |
| } | |
| } | |
| ``` | |
| **For Cursor IDE:** | |
| Add to `.cursorrules` or MCP settings: | |
| ```json | |
| { | |
| "mcpServers": { | |
| "finnhub": { | |
| "command": "python", | |
| "args": ["/absolute/path/to/mcp_server.py"], | |
| "env": { | |
| "FINNHUB_API_KEY": "your_finnhub_api_key_here" | |
| } | |
| } | |
| } | |
| } | |
| ``` | |
| **For Other MCP Clients:** | |
| Use similar command-based configuration with: | |
| - `command`: "python" | |
| - `args`: ["path/to/mcp_server.py"] | |
| - `env`: Set FINNHUB_API_KEY | |
| **Important:** This server uses standard MCP protocol (JSON-RPC over SSE) and is compatible with any MCP client that supports the official MCP specification. | |
| #### 7️⃣ Restart Your MCP Client | |
| Restart Claude Desktop / Cursor to load the new server configuration. | |
| #### 8️⃣ Test the Connection | |
| In your MCP client, try asking: | |
| - "What's the current price of Apple stock?" | |
| - "Show me the latest market news" | |
| - "Get Tesla company news from the past week" | |
| ### 🔧 Tool Usage Examples | |
| #### Example 1: Get Stock Quote | |
| **Natural Language Query:** | |
| ``` | |
| User: "What's the current price of Apple and Microsoft?" | |
| ``` | |
| **MCP Client Actions:** | |
| ``` | |
| Calls: get_quote(symbol="AAPL") | |
| Calls: get_quote(symbol="MSFT") | |
| ``` | |
| **Response Includes:** | |
| - Current price, change, percent change | |
| - High, low, open, previous close | |
| - Real-time timestamp | |
| #### Example 2: Get Market News | |
| **Natural Language Query:** | |
| ``` | |
| User: "Show me the latest cryptocurrency market news" | |
| ``` | |
| **MCP Client Actions:** | |
| ``` | |
| Calls: get_market_news(category="crypto") | |
| ``` | |
| **Response Includes:** | |
| - List of news articles (max 10) | |
| - Headlines, summaries, sources | |
| - Publication dates and URLs | |
| #### Example 3: Get Company News | |
| **Natural Language Query:** | |
| ``` | |
| User: "Get me Tesla's recent news from the past month" | |
| ``` | |
| **MCP Client Actions:** | |
| ``` | |
| Calls: get_company_news( | |
| symbol="TSLA", | |
| from_date="2024-10-28", | |
| to_date="2024-11-28" | |
| ) | |
| ``` | |
| **Response Includes:** | |
| - Company-specific news articles | |
| - Headlines, summaries, sources | |
| - Related stock symbols mentioned | |
| ### 📊 Example Conversation | |
| ``` | |
| You: "I'm interested in tech stocks. Can you show me Apple's current price | |
| and recent news?" | |
| Claude (using MCP tools): | |
| 1. Calls get_quote(symbol="AAPL") | |
| 2. Calls get_company_news(symbol="AAPL") | |
| Claude: "Here's the information about Apple (AAPL): | |
| Current Stock Price: $185.50 | |
| Change: +$2.30 (+1.26%) | |
| Day Range: $183.20 - $186.00 | |
| Recent News: | |
| 1. Apple Announces New Product Line | |
| Source: TechCrunch | Published: 2024-11-27 | |
| [Full article link] | |
| 2. Apple Stock Reaches New High | |
| Source: Bloomberg | Published: 2024-11-26 | |
| [Full article link] | |
| ..." | |
| ``` | |
| ### ⚠️ Troubleshooting | |
| **❌ "Server not responding" or "Connection failed"** | |
| - Verify you ran `python app.py --mcp` | |
| - Check the file path in your MCP config is correct | |
| - Ensure Python is accessible from command line | |
| **❌ "API key not configured"** | |
| - Check `.env` file exists and contains `FINNHUB_API_KEY` | |
| - Or verify `env` section in MCP config has your key | |
| - Restart MCP server after setting the key | |
| **❌ "Invalid symbol" or "No data found"** | |
| - Use correct ticker symbols (e.g., "AAPL" not "Apple") | |
| - Check if market is open (data may be delayed when closed) | |
| - Company news only available for North American companies | |
| **❌ "Rate limit exceeded"** | |
| - Free tier: 60 API calls per minute | |
| - Wait one minute before making more requests | |
| - Consider upgrading Finnhub plan for higher limits | |
| ### 💡 Tips for Best Experience | |
| 1. **Use Natural Language**: Your MCP client understands context. Ask questions naturally. | |
| 2. **Multiple Queries**: You can ask about multiple stocks in one conversation. | |
| 3. **Context Aware**: The client remembers previous queries in the conversation. | |
| 4. **Combine Tools**: Ask for both price and news for comprehensive analysis. | |
| 5. **Date Ranges**: Specify date ranges for historical company news. | |
| ### 🔐 Security Notes | |
| - API keys are stored in environment variables or .env file (not committed to git) | |
| - Never share your Finnhub API key publicly | |
| - The .env file is in .gitignore for security | |
| - MCP server runs locally on your machine | |
| ## 🛠️ Available MCP Tools | |
| ### get_quote | |
| Get real-time quote data for US stocks. | |
| **Parameters:** | |
| - `symbol` (str): Stock symbol (e.g., 'AAPL', 'MSFT', 'TSLA') | |
| **Returns:** Real-time quote data including current price, change, percent change, high, low, open, and previous close | |
| **Example:** | |
| ``` | |
| get_quote(symbol="AAPL") | |
| ``` | |
| ### get_market_news | |
| Get latest market news. | |
| **Parameters:** | |
| - `category` (str, optional): News category. Options: general, forex, crypto, merger. Default: general | |
| - `min_id` (int, optional): Minimum news ID for pagination. Default: 0 | |
| **Returns:** List of latest market news articles with headline, summary, source, URL, and publish time | |
| **Example:** | |
| ``` | |
| get_market_news(category="general") | |
| ``` | |
| ### get_company_news | |
| List latest company news by symbol (North American companies only). | |
| **Parameters:** | |
| - `symbol` (str): Company stock symbol (e.g., 'AAPL', 'MSFT', 'TSLA') | |
| - `from_date` (str, optional): From date in YYYY-MM-DD format. Default: 7 days ago | |
| - `to_date` (str, optional): To date in YYYY-MM-DD format. Default: today | |
| **Returns:** List of latest company news articles with headline, summary, source, URL, and publish time | |
| **Example:** | |
| ``` | |
| get_company_news(symbol="AAPL", from_date="2024-01-01", to_date="2024-01-31") | |
| ``` | |
| ## 🔑 Getting Your API Key | |
| 1. Visit [Finnhub.io](https://finnhub.io/register) | |
| 2. Create a free account | |
| 3. Copy your API key from the dashboard | |
| 4. Configure it in the MCP server | |
| The free tier includes: | |
| - 60 API calls/minute | |
| - Real-time stock quotes | |
| - Market and company news | |
| - And more! | |
| ## 📦 Local Development | |
| ### Installation | |
| ```bash | |
| git clone https://github.com/yourusername/MarketInfoMCP.git | |
| cd MarketInfoMCP | |
| pip install -r requirements.txt | |
| ``` | |
| ### Configuration | |
| Set your Finnhub API key as an environment variable: | |
| ```bash | |
| export FINNHUB_API_KEY="your_api_key_here" | |
| ``` | |
| Or create a `.env` file: | |
| ``` | |
| FINNHUB_API_KEY=your_api_key_here | |
| ``` | |
| ### Run the Server | |
| ```bash | |
| python app.py | |
| ``` | |
| The server will start on `http://localhost:7860` with both the web UI and MCP server enabled. | |
| ## 🌐 Deploying to Hugging Face Spaces | |
| 1. Create a new Space on Hugging Face | |
| 2. Choose "Gradio" as the SDK | |
| 3. Upload the following files: | |
| - `app.py` | |
| - `requirements.txt` | |
| - `README.md` | |
| 4. The Space will automatically deploy | |
| Users can configure their API key through the web interface. | |
| ## 📚 Technology Stack | |
| - **fastMCP** - Fast, Pythonic MCP server framework | |
| - **Gradio** - Web UI and MCP server hosting | |
| - **Finnhub API** - Real-time financial data | |
| - **Python 3.8+** - Runtime environment | |
| ## 📖 API Reference | |
| For detailed Finnhub API documentation, visit: | |
| - [Finnhub API Docs](https://finnhub.io/docs/api) | |
| - [Quote API](https://finnhub.io/docs/api/quote) | |
| - [Market News API](https://finnhub.io/docs/api/market-news) | |
| - [Company News API](https://finnhub.io/docs/api/company-news) | |
| ## 🤝 Contributing | |
| Contributions are welcome! Feel free to open issues or submit pull requests. | |
| ## 📄 License | |
| MIT License - feel free to use this project for your own purposes. | |
| ## 🔗 Links | |
| - [Hugging Face Space](https://huggingface.co/spaces/JC321/MarketandStockMCP) | |
| - [Finnhub API](https://finnhub.io) | |
| - [fastMCP Documentation](https://gofastmcp.com) | |
| - [Model Context Protocol](https://modelcontextprotocol.io) | |
| ## ⚠️ Disclaimer | |
| This tool is for informational purposes only. Always verify information from official sources before making investment decisions. | |