📈 Financial Data MCP Server

Bridge your LLM to real-time structured financial data using the Model Context Protocol (MCP).

---

📌 Overview

The Financial Data MCP Server is a production-ready middleware that connects AI assistants (Claude Desktop, Cursor, or any MCP-compatible client) to a structured PostgreSQL financial database.

Instead of relying on hallucinated financial numbers, your AI can now query a real database to retrieve:

• 📊 Company profiles
• 📈 Financial statements
• 📉 Historical stock data
• 🔍 Multi-company comparisons

This ensures AI-generated financial analysis is accurate, structured, and reliable.

---

🧠 Problem It Solves

Large Language Models are powerful — but they:

• ❌ Cannot access live databases by default
• ❌ May hallucinate financial data
• ❌ Lack structured validation

This MCP server solves that by:

• ✅ Exposing strongly-typed tools
• ✅ Validating inputs using Zod
• ✅ Querying real PostgreSQL data
• ✅ Returning structured JSON responses

AI + Real Data = Trustworthy Insights

---

🏗️ Architecture

User → AI Assistant (Claude / Cursor)
                │
                ▼
        Model Context Protocol
                │
                ▼
     Financial MCP Server (Node.js)
                │
                ▼
     Supabase PostgreSQL Database

🔄 Example Flow

User asks:

Compare Apple and Microsoft revenue over the last 4 quarters.

AI calls MCP tool:

{
  "symbols": ["AAPL", "MSFT"],
  "metric": "revenue"
}

Server queries database → Returns structured JSON → AI generates accurate analysis.

---

🚀 Features

📊 Company Intelligence

• Company name
• CEO
• Sector & industry
• Market capitalization

📈 Financial Reports

• Quarterly revenue
• Annual revenue
• Net income
• EPS
• EBITDA
• Profit margins

📉 Historical Stock Data

• OHLC (Open, High, Low, Close)
• Volume
• Date filtering
• Custom time ranges

🔍 Company Comparisons

• Side-by-side metric comparison
• Clean structured responses
• Optimized for AI analysis

---

🛠️ Tech Stack

Layer	Technology
Runtime	Node.js (v18+)
Language	TypeScript
Protocol	Model Context Protocol (MCP)
Database	Supabase (PostgreSQL)
Validation	Zod
Transport	Stdio

---

📂 Project Structure

mcp-financial-server/
├── src/
│   ├── config/          # Environment configuration
│   ├── db/              # Supabase client setup
│   ├── tools/           # Tool definitions & SQL queries
│   ├── index.ts         # MCP server entry point
│   └── seed.ts          # Database seeding script
│
├── database/
│   └── schema.sql       # SQL schema
│
├── dist/                # Compiled JavaScript
├── .env                 # Environment variables (DO NOT COMMIT)
├── package.json
├── tsconfig.json
└── README.md

---

⚡ Quick Start

1️⃣ Prerequisites

• Node.js v18+
• npm or yarn
• Supabase account (Free tier works)

---

2️⃣ Clone the Repository

git clone https://github.com/yourusername/mcp-financial-server.git
cd mcp-financial-server

---

3️⃣ Install Dependencies

npm install

---

4️⃣ Setup Environment Variables

Create a .env file:

touch .env

Add your credentials:

SUPABASE_URL="your_supabase_project_url"
SUPABASE_SERVICE_KEY="your_service_role_key"

⚠️ Never commit .env to version control.

---

5️⃣ Setup Database

1. Open Supabase dashboard
2. Create a new project
3. Go to SQL Editor
4. Run database/schema.sql

---

6️⃣ Seed Sample Data (Optional)

npm run seed

---

7️⃣ Build the Project

npm run build

---

8️⃣ Start MCP Server

npm start

The server will run over stdio transport and be ready for MCP-compatible clients.

---

🔌 Connecting to Claude Desktop

Add this configuration:

{
  "mcpServers": {
    "financial-data": {
      "command": "node",
      "args": ["dist/index.js"]
    }
  }
}

Restart Claude Desktop after updating configuration.

---

🛡️ Security Best Practices

• Store service role key securely
• Never expose .env publicly
• Restrict database access in production
• Validate all inputs using Zod schemas

---

📌 Example Use Cases

• AI-powered stock analysis assistant
• Automated financial research
• Investor comparison tools
• Portfolio performance dashboards
• Startup valuation research

---

👨‍💻 Author -ANWAY DURGE

Built using TypeScript, Supabase, and the Model Context Protocol (MCP).

If this project helped you, consider giving it a ⭐ on GitHub.