> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your Financial MCP Server running in under 5 minutes

## Overview

This quickstart guide will have you running the Financial MCP Server locally and making your first API calls within minutes.

<Info>
  **Prerequisites**: Python 3.8+, Git, and a terminal/command prompt
</Info>

## Step 1: Clone and Setup

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/your-org/financial-mcp-server.git
    cd financial-mcp-server
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Set Environment Variables">
    ```bash theme={null}
    # Required for FMP professional tools
    export FMP_API_KEY="your_fmp_api_key_here"

    # Optional: Set custom port (default: 8000)
    export PORT=8001
    ```

    <Tip>
      Get a free FMP API key at [Financial Modeling Prep](https://financialmodelingprep.com/developer/docs)
    </Tip>
  </Step>
</Steps>

## Step 2: Start the Server

```bash theme={null}
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)
```

<Check>
  **Success!** Your server is now running on `http://localhost:8001`
</Check>

<Note>
  **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.
</Note>

## Step 3: Test Your Installation

### Option A: Using cURL

<CodeGroup>
  ```bash Stock Quote theme={null}
  curl "http://localhost:8001/api/v1/stock/AAPL"
  ```

  ```bash Market Gainers theme={null}
  curl "http://localhost:8001/api/v1/market/gainers"
  ```

  ```bash Crypto Prices theme={null}
  curl "http://localhost:8001/api/v1/crypto"
  ```
</CodeGroup>

### Option B: Interactive API Documentation

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

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/ntg-c0edb0d4/images/swagger-ui.png" alt="Swagger UI Interface" />
</Frame>

## Step 4: Example Responses

### Stock Quote Response

```json theme={null}
{
  "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

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

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Stock Data" icon="chart-line" href="/api-reference/stock/quote">
    * Real-time quotes
    * Company overviews
    * Historical data
  </Card>

  <Card title="Market Data" icon="trending-up" href="/api-reference/market/gainers">
    * Market gainers/losers
    * Most active stocks
    * Sector performance
  </Card>

  <Card title="FMP Professional" icon="building" href="/api-reference/fmp/financials">
    * Financial statements
    * Key metrics & ratios
    * DCF valuations
  </Card>

  <Card title="Advanced Tools" icon="filter" href="/api-reference/fmp/screening">
    * Stock screening
    * Options analysis
    * Technical indicators
  </Card>
</CardGroup>

## MCP Protocol Usage

For AI agents using the Model Context Protocol:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "get_stock_quote",
    "arguments": {
      "symbol": "AAPL"
    }
  }
}
```

<Info>
  The server automatically handles both MCP and REST protocols on the same port.
</Info>

## Common Issues

<AccordionGroup>
  <Accordion title="Port Already in Use">
    If you see "Address already in use", either:

    * Kill existing processes: `pkill -f "python3 main.py"`
    * Use a different port: `export PORT=8002`
  </Accordion>

  <Accordion title="YFinance Rate Limiting">
    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
  </Accordion>

  <Accordion title="Missing FMP API Key">
    Some advanced features require an FMP API key:

    * Get a free key at [Financial Modeling Prep](https://financialmodelingprep.com/developer/docs)
    * Set it with: `export FMP_API_KEY="your_key"`
    * Basic YFinance tools work without an API key
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy to Production" icon="rocket" href="/guides/deployment">
    Deploy to Railway, Heroku, or your preferred platform
  </Card>

  <Card title="Frontend Integration" icon="code" href="/guides/frontend-integration">
    Connect your web application or mobile app
  </Card>

  <Card title="MCP Integration" icon="robot" href="/concepts/mcp-protocol">
    Integrate with Claude or other AI agents
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all 32 available financial tools
  </Card>
</CardGroup>

Ready to dive deeper? Check out our [API Reference](/api-reference/introduction) for complete documentation of all endpoints and tools.