# 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
