README.md

metadata

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
2. Go to the Configuration tab
3. Enter your Finnhub API key (get one free at finnhub.io)
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:

# Run the standalone MCP server
python mcp_server.py

Then configure your MCP client:

{
  "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:

# Run the MCP server mode
python app.py --mcp

Then configure your MCP client:

{
  "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)
• An MCP-compatible client (Claude Desktop, Cursor, etc.)

2️⃣ Clone the Repository

git clone https://huggingface.co/spaces/JC321/MarketandStockMCP
cd MarketandStockMCP

3️⃣ Install Dependencies

pip install -r requirements.txt

4️⃣ Configure API Key

Option A: Environment Variable

# 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

# Create .env file
echo "FINNHUB_API_KEY=your_api_key_here" > .env

5️⃣ Run the MCP Server

Recommended: Use the standalone MCP server

python mcp_server.py

Or use app.py with --mcp flag:

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:

{
  "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:

{
  "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
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

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:

export FINNHUB_API_KEY="your_api_key_here"

Or create a .env file:

FINNHUB_API_KEY=your_api_key_here

Run the Server

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
• Quote API
• Market News API
• Company News API

🤝 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
• Finnhub API
• fastMCP Documentation
• Model Context Protocol

⚠️ Disclaimer

This tool is for informational purposes only. Always verify information from official sources before making investment decisions.