mcp-stock-server by mrkivan - MCP Server

📘MCP Stock Tools Server

A lightweight Model Context Protocol (MCP) server built with FastMCP, providing AI-accessible tools for fetching real-time and historical stock data from Finnhub and Twelve Data.

🚀 Features

🔹 Real-time stock quotes from Finnhub
🔹 Historical daily stock prices from Twelve Data (configurable by months)
🔹 FastMCP-compatible — easy integration with LLMs and AI clients
🔹 HTTP/SSE transport support
🔹 Simple to run locally or deploy in production

🧩 Tech Stack

Component	Description
FastMCP	Lightweight MCP server framework
Python 3.9+	Core runtime
Requests	For calling external stock APIs
HTTP Transport (SSE)	Enables remote MCP client connections

⚙️ Installation

1️⃣ Clone the repository

git clone https://github.com/your-username/mcp-stock-tools.git
cd mcp-stock-tools

2️⃣ Install dependencies

pip install fastmcp requests

3️⃣ Set your API keys

You need free API keys from Finnhub.io and TwelveData.com.

macOS/Linux:

export FINNHUB_API_KEY=your_finnhub_api_key
export TWELVEDATA_API_KEY=your_twelvedata_api_key

Windows (PowerShell):

setx FINNHUB_API_KEY "your_finnhub_api_key"
setx TWELVEDATA_API_KEY "your_twelvedata_api_key"

▶️ Running the Server

python server.py

If successful, you’ll see:

Starting MCP server on http://127.0.0.1:8000/mcp

This runs an HTTP-based MCP server with two tools:

fetch_finnhub_quote — real-time price from Finnhub
fetch_twelve_data_history — daily price history from Twelve Data

💡 Example MCP Tools

`fetch_finnhub_quote`

Fetch the latest stock price.

result = await client.call_tool("fetch_finnhub_quote", {"symbol": "AAPL"})

Output:

{
  "c": 189.7,
  "h": 190.5,
  "l": 188.2,
  "o": 189.1,
  "pc": 188.8,
  "t": 1731498361
}

`fetch_twelve_data_history`

Fetch historical daily data for the last N months (1–12).

result = await client.call_tool("fetch_twelve_data_history", {"symbol": "AAPL", "months": 3})

Output (truncated):

{
  "meta": {...},
  "values": [
    {"datetime": "2025-11-11", "open": "189.5", "close": "190.1", "high": "191.0", "low": "188.9"},
    ...
  ]
}

🧠 Example Client

You can test your server using the FastMCP client: client.py

Run it:

python client.py

🧪 Debugging / Development Tips

📝 Logs are printed to console for easy debugging
❌ If you see “API error,” check your API key limits or connectivity
🔌 You can connect with any MCP-compatible LLM or app (e.g., Claude Desktop)

🔒 Environment Variables

Name	Description	Required
`FINNHUB_API_KEY`	API key for finnhub.io	✅
`TWELVEDATA_API_KEY`	API key for twelvedata.com	✅

mrkivan/mcp-stock-server