---
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.