GBS Finance MCP Server

A Model Context Protocol (MCP) server that provides comprehensive financial market data, quotes, historical prices, and analysis tools. This server integrates with the GBS Finance API to deliver real-time and historical financial data for stocks, ETFs, REITs, and other securities.

Features

15 Financial Data Tools

Core Quote & Market Data:

• finance_get_quote - Get single security quote with dividend yields
• finance_get_quotes - Batch quotes for multiple symbols

Historical & Performance Data:

• finance_get_history - Historical OHLC prices (period/interval)
• finance_get_histories - Multi-symbol historical prices
• finance_get_performances - Performance metrics across periods (1mo/ytd/1y/5y)

Security-Type Specific:

• finance_get_etf_data - ETF metrics with expense ratios and returns
• finance_get_stock_data - Stock data with dividend information
• finance_get_reit_data - REIT data with gearing ratios

Financial Analysis:

• finance_get_financial_analysis - Growth metrics & ratio analysis
• finance_get_financials_history - All historical financial statements
• finance_get_earnings_estimates - Forward earnings projections

Singapore-Specific:

• finance_get_ssb_projection - Singapore Savings Bond rate projection
• finance_get_fund_returns - Fullerton fund performance
• finance_get_exchange_rate - Currency conversion rates
• finance_get_dividend_stats - Comprehensive dividend analysis

Installation

Prerequisites

• Node.js 18 or higher
• pnpm (recommended) or npm
• Access to GBS Finance API (default: http://localhost:8000)

Setup

1. Clone or navigate to the project directory:

   cd gbs-finance-mcp

2. Install dependencies:

   pnpm install

3. Configure environment (optional):

   cp .env.example .env
   # Edit .env to set FINANCE_API_URL if different from default

4. Build the project:

   pnpm run build

Usage

Running the Server

The MCP server communicates via stdio (standard input/output):

node dist/index.js

Configuration with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gbs-finance": {
      "command": "node",
      "args": [
        "/absolute/path/to/gbs-finance-mcp/dist/index.js"
      ],
      "env": {
        "FINANCE_API_URL": "http://localhost:8000"
      }
    }
  }
}

Other MCP Clients

Configure according to your client's documentation, using:

• Command: node
• Args: ["/path/to/dist/index.js"]
• Transport: stdio

Tool Examples

Get a Single Quote

{
  "name": "finance_get_quote",
  "arguments": {
    "symbol": "AAPL",
    "response_format": "markdown"
  }
}

Get Historical Prices

{
  "name": "finance_get_history",
  "arguments": {
    "symbol": "AAPL",
    "period": "1y",
    "interval": "1d",
    "response_format": "json"
  }
}

Compare Multiple ETFs

{
  "name": "finance_get_etf_data",
  "arguments": {
    "symbols": ["SPY", "VOO", "QQQ"],
    "response_format": "markdown"
  }
}

Analyze Financial Performance

{
  "name": "finance_get_financial_analysis",
  "arguments": {
    "symbol": "AAPL",
    "response_format": "markdown"
  }
}

Get Singapore Savings Bond Projection

{
  "name": "finance_get_ssb_projection",
  "arguments": {
    "response_format": "markdown"
  }
}

Response Formats

All tools support two output formats:

Markdown (default)

Human-readable format with headers, tables, and formatting:

# Quote: AAPL

**Price**: USD 150.25
**Change**: USD 2.50 (1.69%)
...

JSON

Machine-readable structured data:

{
  "symbol": "AAPL",
  "regularMarketPrice": 150.25,
  "regularMarketChange": 2.50,
  ...
}

Specify format using the response_format parameter: "markdown" or "json".

Development

Project Structure

gbs-finance-mcp/
├── src/
│   ├── index.ts          # Main MCP server + all tool implementations
│   ├── constants.ts      # API URLs, limits, enums
│   ├── types.ts          # TypeScript type definitions
│   ├── schemas/
│   │   └── finance.ts    # Zod validation schemas
│   └── utils/
│       ├── api.ts        # HTTP client wrapper
│       └── format.ts     # Response formatters
├── dist/                 # Built JavaScript files
├── package.json
├── tsconfig.json
└── README.md

Development Commands

# Development with auto-reload
pnpm run dev

# Build TypeScript to JavaScript
pnpm run build

# Clean build artifacts
pnpm run clean

# Run the server
pnpm start

Code Quality

• Strict TypeScript: Full type safety enabled
• Zod Validation: Runtime input validation for all tools
• Error Handling: Comprehensive error messages with actionable guidance
• Response Limits: 25,000 character limit with graceful truncation
• Tool Annotations: All tools annotated with readOnlyHint, destructiveHint, idempotentHint, openWorldHint

Architecture

MCP Server Design

This server follows MCP best practices:

1. Agent-Centric Design: Tools enable complete workflows, not just API wrappers
2. Optimized for Context: Dual format support (Markdown/JSON) for efficient LLM consumption
3. Actionable Errors: Error messages guide next steps
4. Natural Task Subdivision: Tool names reflect how humans think about tasks
5. Read-Only Operations: All tools are non-destructive with readOnlyHint=true

API Integration

The server connects to the GBS Finance FastAPI backend which:

• Fetches data from Yahoo Finance (yahooquery)
• Caches responses for performance
• Provides SGX-specific dividend calculations
• Integrates with Temporal workflows for data updates
• Stores data in MySQL database

Troubleshooting

Server Won't Start

Error: Cannot connect to finance API

• Ensure the GBS Finance API is running at the configured URL
• Check FINANCE_API_URL environment variable
• Default is http://localhost:8000

Error: Module not found

• Run pnpm install to install dependencies
• Run pnpm run build to compile TypeScript

Data Issues

Error: Resource not found (404)

• Verify the symbol is correct and exists in the database
• Check if the security has been imported into the finance system
• Some symbols may only have limited data available

Response Truncated:

• Use pagination parameters (limit/offset) to fetch data in chunks
• Add filters to reduce result set size
• Use JSON format for more efficient data representation

API Requirements

This MCP server requires the GBS Finance API to be running. See the main gbs-finance project for:

• API setup instructions
• Database migrations
• Temporal worker configuration
• Data population workflows

License

MIT

Contributing

This server is part of the GBS Finance project. For issues or contributions, please refer to the main project repository.

Support

For questions or issues:

1. Check the troubleshooting section above
2. Review the main GBS Finance project documentation
3. Ensure all dependencies are installed and up to date

Note: This is a read-only MCP server. All tools perform non-destructive data retrieval operations only. No data modifications are possible through this interface.