# Financial Data MCP Server

A production-ready **Model Context Protocol (MCP)** server that connects AI models to real-time financial market data via the Alpha Vantage API.

Built by **Rajith P R** as part of a GenAI engineering portfolio, demonstrating hands-on MCP implementation, async Python, and enterprise API integration patterns.

---

## What Is MCP?

Model Context Protocol (MCP) is an open standard by Anthropic that allows AI models (like Claude) to securely connect to external tools, APIs, and data sources. This server implements the MCP specification to expose financial data as callable tools that any compatible AI client can use.

---

## Tools Exposed

| Tool | Description |
|------|-------------|
| `get_stock_quote` | Real-time price, change, volume, and trading range for any ticker |
| `get_company_overview` | Fundamentals: market cap, P/E ratio, EPS, dividend yield, analyst target |
| `get_daily_prices` | OHLCV time series for the last N trading days (max 30) |
| `search_symbol` | Search for ticker symbols by company name or keyword |
| `get_market_status` | Open/closed status for major global exchanges (NYSE, LSE, NSE, etc.) |

---

## Architecture

```
AI Client (Claude Desktop / any MCP client)
        |
        | MCP Protocol (stdio / SSE)
        v
  financial-mcp-server (FastMCP)
        |
        | HTTPS (httpx async)
        v
  Alpha Vantage Financial Data API
```

- **Transport:** stdio (default) — MCP-standard, works with Claude Desktop out of the box
- **HTTP client:** `httpx` with async/await for non-blocking API calls
- **Error handling:** API rate limits, invalid symbols, and network failures all return structured messages
- **LLM-agnostic:** No dependency on any specific AI provider — works with Claude, GPT, Gemini, or any MCP client

---

## Quick Start

### 1. Clone and install

```bash
git clone https://github.com/rajithputhurath/financial-mcp-server.git
cd financial-mcp-server
pip install -r requirements.txt
```

### 2. Configure API key

```bash
cp .env.example .env
# Edit .env and add your Alpha Vantage API key
# Free key: https://www.alphavantage.co/support/#api-key
# 'demo' key works for IBM symbol only
```

### 3. Test all tools (no MCP client needed)

```bash
python tests/test_tools.py
```

### 4. Connect to Claude Desktop

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "financial-data": {
      "command": "python",
      "args": ["/absolute/path/to/financial-mcp-server/server.py"],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You will see the financial tools available in the tools panel.

---

## Example Interactions (via Claude Desktop)

Once connected, you can ask Claude:

- *"What is Apple's current stock price?"*
- *"Give me the fundamentals for Infosys"*
- *"Show me Microsoft's daily prices for the last 2 weeks"*
- *"Search for HSBC's ticker symbol"*
- *"Are the London and New York stock exchanges open right now?"*

Claude will automatically select and call the appropriate tool.

---

## Project Structure

```
financial-mcp-server/
├── server.py                   # MCP server with all 5 tools
├── requirements.txt
├── .env.example                # API key template
├── claude_desktop_config.json  # Claude Desktop connection config
└── tests/
    └── test_tools.py           # CLI test runner (no MCP client needed)
```

---

## Key Technical Decisions

**Why FastMCP?**
FastMCP is the official high-level Python SDK for building MCP servers. It handles protocol negotiation, tool registration, and transport — letting the code focus on business logic.

**Why async/await throughout?**
Financial API calls are I/O-bound. Async HTTP via `httpx` keeps the server responsive and avoids blocking the MCP event loop.

**Why LLM-agnostic?**
MCP is an open protocol. This server works with Claude, GPT-4, Gemini, or any future client that implements MCP — maximising reusability.

**Why Alpha Vantage?**
Free tier with no credit card, covers equities globally (US, UK, India, etc.), and returns clean JSON. Suitable for portfolio projects and proof-of-concept implementations.

---

## API Limits (Free Tier)

- 25 requests/day
- `demo` API key: IBM symbol only
- Free API key (register on Alpha Vantage): all symbols, 25 requests/day
- Premium key: higher rate limits, real-time data

---

## Author

**Rajith P R** — Senior Technical Consultant and AI Engineer  
[LinkedIn](https://linkedin.com/in/rajithputhurath) | rajithputhurath@gmail.com

Hands-on experience with Model Context Protocol, Python data pipelines, REST API integration, and enterprise automation at LSEG (London Stock Exchange Group).

---

## License

MIT License. Free to use and adapt with attribution.