Skip to main content

​
Overview

This quickstart guide will have you running the Financial MCP Server locally and making your first API calls within minutes.
Prerequisites: Python 3.8+, Git, and a terminal/command prompt

​
Step 1: Clone and Setup

1

Clone the Repository

git clone https://github.com/your-org/financial-mcp-server.git
cd financial-mcp-server
2

Install Dependencies

pip install -r requirements.txt
3

Set Environment Variables

# Required for FMP professional tools
export FMP_API_KEY="your_fmp_api_key_here"

# Optional: Set custom port (default: 8000)
export PORT=8001
Get a free FMP API key at Financial Modeling Prep

​
Step 2: Start the Server

python3 main.py
You should see output like this: 
🚀 Starting Enhanced Financial MCP Server
📡 MCP Protocol: http://0.0.0.0:8001/
🌐 REST API: http://0.0.0.0:8001/api/v1/
📚 API Docs: http://0.0.0.0:8001/docs
🔧 Tools Available: 32 (6 YFinance + 26 FMP)
Success! Your server is now running on http://localhost:8001
Live Demo Available: You can also test the API using our live Railway deployment at https://stocks-dev.up.railway.app/api/v1/ without setting up locally.

​
Step 3: Test Your Installation

​
Option A: Using cURL

curl "http://localhost:8001/api/v1/stock/AAPL"

​
Option B: Interactive API Documentation

Visit http://localhost:8001/docs in your browser to access the interactive Swagger UI documentation.
Swagger UI Interface

​
Step 4: Example Responses

​
Stock Quote Response

{
  "symbol": "AAPL",
  "price": 201.08,
  "change": 0.08,
  "changesPercentage": 0.039801,
  "dayLow": 200.62,
  "dayHigh": 203.22,
  "yearHigh": 260.1,
  "yearLow": 169.21,
  "marketCap": 3003290664000,
  "volume": 70534466,
  "exchange": "NASDAQ",
  "source": "FMP",
  "timestamp": "2025-06-28T18:42:12.471731"
}

​
Market Gainers Response

{
  "gainers": [
    {
      "ticker": "JEM",
      "changes": 0.57,
      "price": "6.3",
      "changesPercentage": "9.94764",
      "companyName": "707 Cayman Holdings Limited"
    }
  ]
}

​
Available Endpoints

Stock Data

  • Real-time quotes
  • Company overviews
  • Historical data

Market Data

  • Market gainers/losers
  • Most active stocks
  • Sector performance

FMP Professional

  • Financial statements
  • Key metrics & ratios
  • DCF valuations

Advanced Tools

  • Stock screening
  • Options analysis
  • Technical indicators

​
MCP Protocol Usage

For AI agents using the Model Context Protocol: 
{
  "method": "tools/call",
  "params": {
    "name": "get_stock_quote",
    "arguments": {
      "symbol": "AAPL"
    }
  }
}
The server automatically handles both MCP and REST protocols on the same port.

​
Common Issues

If you see “Address already in use”, either:
  • Kill existing processes: pkill -f "python3 main.py"
  • Use a different port: export PORT=8002
YFinance may get rate limited by Yahoo Finance. The server automatically:
  • Implements retry logic with exponential backoff
  • Falls back to FMP data when available
  • Provides clear error messages
Some advanced features require an FMP API key:
  • Get a free key at Financial Modeling Prep
  • Set it with: export FMP_API_KEY="your_key"
  • Basic YFinance tools work without an API key

​
Next Steps

Deploy to Production

Deploy to Railway, Heroku, or your preferred platform

Frontend Integration

Connect your web application or mobile app

MCP Integration

Integrate with Claude or other AI agents

API Reference

Explore all 32 available financial tools
Ready to dive deeper? Check out our API Reference for complete documentation of all endpoints and tools.