# Financial MCP Server

A production-ready Model Context Protocol (MCP) server that enables AI assistants (Claude Desktop, ChatGPT Desktop) to query financial data from three different sources.

## Features

- **Exchange Rates** - Real-time currency conversion using public API
- **Stock Market Data** - Live stock quotes via Alpha Vantage API
- **Transaction Database** - CSV-based local database with sample financial data
- **Dual Mode** - Runs locally (Stdio) or as a Web Service (SSE)

## 🌐 Live Demo

You can connect to the hosted server directly without installing anything.

### Option 1: Claude Desktop (Visual)
1.  Open similar dialog to "Add custom connector" (if available in your version).
2.  **Name**: `Financial Mcp Demo`
3.  **URL**: `https://financial-mcp.el-hamdani.com/sse`

<img width="538" height="397" alt="image" src="https://github.com/user-attachments/assets/d9c94152-8882-4d6f-9a52-3fe62146a2fd" />


### Option 2: OpenAI / ChatGPT (Actions)
1.  Click "New App" or "Add Action".
2.  **Name**: `Financial Mcp Demo`
3.  **MCP Server URL**: `https://financial-mcp.el-hamdani.com/sse`
4.  **Authentication**: None / None (Public API)

<img width="450" height="679" alt="image" src="https://github.com/user-attachments/assets/6d5754e4-8946-4f5f-a35b-feccd2317de6" />


### Option 3: Claude Desktop (Config File)
Add this to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "financial-mcp-demo": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse-client",
        "https://financial-mcp.el-hamdani.com/sse"
      ]
    }
  }
}
```

## Quick Start

### Installation

```bash
npm install
npm run build
```

### Configuration

#### Claude Desktop

Add to your Claude Desktop configuration:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

### Optional: Stock Market Data

To enable stock market tools, get a free API key from [Alpha Vantage](https://www.alphavantage.co/support/#api-key) and add it to the configuration.

## Available Tools

### Exchange Rate Tools

| Tool | Description |
|------|-------------|
| `get_exchange_rate` | Get exchange rate between two currencies |
| `convert_currency` | Convert an amount from one currency to another |
| `get_multiple_rates` | Get rates from one currency to multiple targets |

### Stock Market Tools

| Tool | Description |
|------|-------------|
| `get_stock_quote` | Get current stock quote for a symbol |
| `compare_stocks` | Compare multiple stock quotes |

### Transaction Tools

| Tool | Description |
|------|-------------|
| `query_transactions` | Search and filter financial transactions |
| `get_spending_by_category` | Get spending breakdown by category |
| `get_spending_by_department` | Get spending breakdown by department |
| `compare_to_budget` | Compare actual spending vs budget |
| `get_top_vendors` | Get top vendors by spending |

## Example Queries

### Exchange Rates
- "What's the EUR to USD exchange rate?"
- "Convert 10,000 EUR to USD"
- "Show me rates from EUR to USD, GBP, JPY, CHF"

### Transactions
- "What were our total expenses in Q4 2024?"
- "Show me all software purchases over 1,000 EUR"
- "Which department spent the most on travel?"
- "Are we over budget in any category?"
- "Who are our top 5 vendors?"

### Stocks (requires API key)
- "What's Apple's current stock price?"
- "Compare Microsoft, Google, and Apple stocks"

## Sample Data

The database includes 23 sample transactions across:
- **Departments:** Engineering, Sales, Marketing
- **Categories:** Software, Hardware, Travel, Marketing
- **Time Period:** Q4 2024 - Q1 2025

## Project Structure

```
financial-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts           # Main server entry
│   ├── types.ts           # TypeScript interfaces
│   ├── services/          # Data access layer
│   │   ├── exchangeRate.ts
│   │   ├── stockData.ts
│   │   └── database.ts
│   └── tools/             # MCP tool implementations
│       ├── exchangeRate.ts
│       ├── stockData.ts
│       └── transactions.ts
└── data/
    ├── transactions.csv
    └── budgets.csv
```

## Development

```bash
# Build
npm run build

# Watch mode
npm run watch
```

## License

MIT