MCP-FinTechCo Server

A production-ready Model Context Protocol (MCP) server built with FastMCP 2.0, providing comprehensive financial technology and economic data tools.

Overview

MCP-FinTechCo is a powerful, scalable FinTech and economic data MCP server designed for real-world financial applications, algorithmic trading, portfolio management, market analysis, and economic research.

What is MCP? The Model Context Protocol is a standardized way to connect large language models (LLMs) to external tools and data sources. Think of it as "the USB-C port for AI" - it provides a uniform interface for AI applications to access financial data, execute functions, and interact with real-time market information.

Built on FastMCP 2.0, this server provides robust access to:

• Real-time market data through the Alpha Vantage API (stock quotes, FX rates, crypto prices)
• Comprehensive economic indicators through the Federal Reserve Economic Data (FRED) API
• Technical analysis with built-in indicators (SMA, RSI)
• Economic research tools with historical time series data

Key Features

• FastMCP 2.0 Framework: Modern, production-ready MCP implementation optimized for financial and economic data
• Alpha Vantage Integration: Comprehensive access to global financial markets
• FRED API Integration: 400,000+ US and global economic indicators
• Real-Time Market Data: Stock quotes, FX rates, and cryptocurrency prices
• Economic Indicators: GDP, CPI, unemployment, and thousands more
• Technical Analysis: Built-in indicators (SMA, RSI)
• Cloud-Ready: Designed for deployment on Google Cloud Platform
• Extensible Architecture: Easy to add new financial and economic tools
• Tag-Based Discovery: All tools tagged for easy filtering and discoverability
• Interactive Testing: CLI chat interface powered by Claude AI
• Comprehensive Logging: Built-in monitoring and debugging capabilities

Financial Data Tools

Stock Market Tools

get_stock_quote

Get real-time stock quotes for any global equity.

Parameters:

• symbol (string): Stock ticker symbol (e.g., "AAPL", "MSFT", "TSLA")

Returns:

{
  "symbol": "AAPL",
  "price": 178.50,
  "change": 2.35,
  "change_percent": "1.33%",
  "volume": 45829304,
  "latest_trading_day": "2025-11-02",
  "previous_close": 176.15,
  "open": 177.20,
  "high": 179.10,
  "low": 176.80
}

get_stock_daily

Retrieve daily time series data (OHLCV - Open, High, Low, Close, Volume).

Parameters:

• symbol (string): Stock ticker symbol
• outputsize (string): "compact" (100 days) or "full" (20+ years)

Returns: Historical daily price data with dates, OHLCV values

Technical Indicators

get_sma

Simple Moving Average - identifies trends and support/resistance levels.

Parameters:

• symbol (string): Stock ticker
• interval (string): "daily", "weekly", "monthly", or intraday ("1min", "5min", etc.)
• time_period (int): Number of data points (default: 20)
• series_type (string): "close", "open", "high", "low"

Returns: Time series of SMA values

get_rsi

Relative Strength Index - measures momentum and overbought/oversold conditions.

Parameters:

• symbol (string): Stock ticker
• interval (string): Time interval
• time_period (int): Lookback period (default: 14)
• series_type (string): Price type

Returns: RSI values (0-100 scale, >70 = overbought, <30 = oversold)

Foreign Exchange

get_fx_rate

Get real-time foreign exchange rates between any two currencies.

Parameters:

• from_currency (string): Source currency code (e.g., "USD", "EUR", "GBP")
• to_currency (string): Target currency code (e.g., "JPY", "CHF", "AUD")

Returns:

{
  "from_currency": "USD",
  "to_currency": "EUR",
  "exchange_rate": 0.9234,
  "bid_price": 0.9233,
  "ask_price": 0.9235,
  "last_refreshed": "2025-11-02 20:15:00"
}

Cryptocurrency

get_crypto_rate

Get real-time cryptocurrency exchange rates.

Parameters:

• symbol (string): Crypto symbol (e.g., "BTC", "ETH", "DOGE")
• market (string): Market currency (default: "USD")

Returns: Real-time crypto price, bid/ask spread, and metadata

Utility Tools

get_city_weather

Get current weather information for any city (demonstration of extensibility).

Parameters:

• city (string): City name (e.g., "New York", "London")

Returns: Temperature, humidity, wind speed, and conditions

Note: The weather tool demonstrates the server's extensibility beyond financial data. Future versions may include additional utility tools.

Economic Data Tools (FRED - Federal Reserve Economic Data)

The MCP server integrates with the Federal Reserve Economic Data (FRED) API, providing access to 400,000+ US and global economic indicators. These tools enable comprehensive economic analysis, research, and integration with financial applications.

Tags: economic-data, fred, indicator, time-series

FRED Series Search & Discovery

search_fred_series

Search for economic indicators in FRED database by keyword.

Parameters:

• search_text (string): Keywords to search (e.g., "unemployment", "GDP", "inflation")
• search_type (string): "full_text" (default) or "series_id" for exact matches
• limit (integer): Max results (1-1000, default: 50)

Returns:

{
  "search_text": "unemployment",
  "count": 50,
  "total_count": 250+,
  "series": [
    {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "units": "Percent",
      "frequency": "Monthly",
      "seasonal_adjustment": "Seasonally Adjusted",
      "observation_start": "1948-01-01",
      "observation_end": "2025-10-01"
    },
    ...
  ]
}

search_series_tags

(NEW) Discover categorization tags for economic series matching a search query.

Parameters:

• search_text (string): Keywords to search (e.g., "inflation", "employment")
• limit (integer): Max tags (1-1000, default: 100)

Returns:

{
  "search_text": "inflation",
  "tags_count": 20,
  "tags": [
    {
      "name": "usa",
      "group_id": "geot",
      "popularity": 100,
      "series_count": 245,
      "notes": "Geographic region: United States"
    },
    ...
  ]
}

Use Cases:

• Discover available tags to refine series searches
• Understand how economic indicators are categorized
• Find related series through tag exploration

search_series_related_tags

(NEW) Find tags related to a search when filtered by existing tags. Advanced exploration tool.

Parameters:

• search_text (string): Keywords to search
• tag_names (string): Semicolon-delimited tag names (e.g., "monthly;sa")
• limit (integer): Max related tags (1-1000, default: 100)

Returns: Related tags that commonly appear with the filter tags

Use Cases:

• Iteratively refine searches by discovering relevant tag combinations
• Explore how attributes (geography, frequency, seasonal adjustment) relate
• Build sophisticated queries for specific indicator types

get_fred_releases

Get list of available FRED economic releases (CPI, Employment, GDP, etc.).

Parameters:

• limit (integer): Max releases (1-1000, default: 50)

Returns: List of economic releases with metadata

get_series_updates

(NEW) Monitor which economic series have been recently updated.

Parameters:

• start_time (string): Filter updates after this time (YYYY-MM-DD, optional)
• end_time (string): Filter updates before this time (YYYY-MM-DD, optional)
• limit (integer): Max series (1-1000, default: 100)

Returns:

{
  "series_count": 50,
  "series": [
    {
      "id": "UNRATE",
      "title": "Unemployment Rate",
      "last_updated": "2025-11-03T08:30:00",
      "observation_end": "2025-10-01",
      ...
    },
    ...
  ]
}

Use Cases:

• Track new economic data releases
• Monitor data revisions for specific indicators
• Build real-time dashboards with latest data
• Create alert systems for important updates

FRED Release Management

get_release_info

(NEW) Get detailed information about a specific FRED economic data release.

Parameters:

• release_id (integer): FRED release ID (e.g., 10, 50)

Returns:

{
  "id": 50,
  "name": "Employment Situation",
  "press_release": true,
  "realtime_start": "2025-01-01",
  "realtime_end": "9999-12-31",
  "link": "http://www.bls.gov/news.release/empsit.toc.htm",
  "notes": "The Employment Situation release from the U.S. Bureau of Labor Statistics..."
}

Use Cases:

• Understand scope and context of specific releases
• Access official release documentation
• Check for press releases with analysis

get_release_series

(NEW) Get all economic series included in a specific FRED release.

Parameters:

• release_id (integer): FRED release ID
• limit (integer): Max series (1-1000, default: 100)

Returns: List of all data series published together in the release

Use Cases:

• Discover all indicators in major releases (e.g., Employment Situation)
• Analyze comprehensive release coverage
• Build dashboards tracking all components of a release

get_release_dates

(NEW) Get historical and upcoming release dates for FRED economic data.

Parameters:

• release_id (integer): FRED release ID
• limit (integer): Max dates (1-1000, default: 100)

Returns:

{
  "release_id": 50,
  "dates_count": 20,
  "release_dates": [
    {"release_id": 50, "date": "2025-11-01"},
    {"release_id": 50, "date": "2025-10-04"},
    ...
  ]
}

Use Cases:

• Schedule monitoring for upcoming releases
• Understand publication frequency patterns
• Plan analysis around data release timing
• Track historical release schedule

FRED Data Retrieval

get_economic_indicator

Get recent time series data for a specific economic indicator.

Parameters:

• series_id (string): FRED series ID (e.g., "UNRATE", "GDP", "CPIAUCSL")
• start_date (string): Start date in YYYY-MM-DD format (optional)
• end_date (string): End date in YYYY-MM-DD format (optional)
• limit (integer): (NEW) Max recent observations (default: 20, max: 100000)

Returns:

{
  "series_id": "UNRATE",
  "observations_count": 20,
  "observations": [
    {"date": "2025-10-01", "value": 4.1},
    {"date": "2025-09-01", "value": 4.2},
    ...
  ]
}

Use Cases:

• Quick check of current indicator values
• Dashboard displaying latest data points
• Recent trend analysis

Note: For comprehensive historical analysis with transformations, use get_series_observations instead.

get_series_metadata

Get detailed metadata for a FRED series.

Parameters:

• series_id (string): FRED series ID

Returns: Title, units, frequency, seasonal adjustment, date ranges, popularity, notes

get_category_series

Get all economic series within a FRED category.

Parameters:

• category_id (integer): FRED category ID (e.g., 12 for employment, 106 for production)
• limit (integer): Max series (1-1000, default: 50)

Returns:

{
  "category_id": 12,
  "category_name": "Employment",
  "series_count": 50,
  "series": [
    {"id": "UNRATE", "title": "Unemployment Rate", ...},
    {"id": "PAYEMS", "title": "Total Nonfarm Payroll", ...},
    ...
  ]
}

get_series_observations

Get detailed observations with advanced filtering and transformations.

Parameters:

• series_id (string): FRED series ID
• start_date (string): Start date (YYYY-MM-DD, optional)
• end_date (string): End date (YYYY-MM-DD, optional)
• frequency (string): Aggregation - "d"(daily), "w"(weekly), "m"(monthly), "q"(quarterly), "a"(annual)
• units (string): Transformation - "lin"(levels), "chg"(change), "pch"(% change), "pca"(% change annual), "log"(log scale)

Returns: Observations with specified transformations applied

Use Cases:

• Full historical analysis requiring transformations
• Research requiring specific time periods
• Calculating growth rates or changes
• Economic forecasting and modeling

get_series_vintagedates

(NEW) Get vintage dates showing when a FRED series was revised or updated.

Parameters:

• series_id (string): FRED series ID (e.g., "GDP", "UNRATE")
• limit (integer): Max vintage dates (1-10000, default: 100)

Returns:

{
  "series_id": "GDP",
  "vintages_count": 50,
  "vintage_dates": [
    "2025-10-30",
    "2025-09-26",
    "2025-08-29",
    ...
  ]
}

Use Cases:

• Study economic data revision patterns and magnitude
• Research real-time vs. final data for forecasting analysis
• Understand data reliability and revision frequency
• Academic research on data quality and measurement
• Track how initial estimates evolve over time

Note: Each vintage date represents a snapshot of the series at that point in time. Series like GDP are frequently revised as better data becomes available. ALFRED (Archival FRED) provides historical vintages for research.

Popular FRED Series IDs

Labor Market:

• UNRATE - Unemployment Rate (%)
• PAYEMS - Total Nonfarm Payroll (Thousands)
• ICSA - Initial Claims

Inflation:

• CPIAUCSL - Consumer Price Index (All Urban Consumers)
• CPILFESL - Core CPI (Excluding Food & Energy)
• DFEDTARU - Federal Funds Rate

GDP & Output:

• GDP - Real Gross Domestic Product (Billions)
• GDPC1 - Real GDP per Capita
• INDPRO - Industrial Production Index

Interest Rates:

• FEDFUNDS - Effective Federal Funds Rate (%)
• DGS10 - 10-Year Treasury Constant Maturity Rate
• DGS2 - 2-Year Treasury Rate

Housing:

• MORTGAGE30US - 30-Year Mortgage Rate
• HOUST - Housing Starts (Thousands)

Installation

Prerequisites

• Python 3.11 or higher
• pip (Python package manager)
• Git
• Alpha Vantage API key (free at https://www.alphavantage.co/support/#api-key)
• FRED API key (free at https://fred.stlouisfed.org/docs/api/api_key.html)

Local Setup

1. Clone the repository:

git clone https://github.com/YOUR-USERNAME/MCP-FinTechCo.git
cd MCP-FinTechCo

2. Create and activate a virtual environment:

Windows:

python -m venv venv
venv\Scripts\activate

Linux/Mac:

python3 -m venv venv
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

cp .env.sample .env

Edit .env and add your API keys:

ALPHA_VANTAGE_API_KEY=your-key-here
FRED_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here  # For chat_test.py

5. Run the server:

python server.py

Usage

Running the Server

Local Development:

python server.py

With Custom Configuration:

export LOG_LEVEL=DEBUG
export MCP_SERVER_PORT=8080
python server.py

Testing the Server

Automated Test Suite:

python test_client.py

This runs automated tests to validate server functionality.

Interactive Chat Test Utility:

python chat_test.py

This launches an advanced interactive chat interface powered by Claude AI for comprehensive testing of MCP server capabilities. See CHAT_TEST_USAGE.md for detailed usage instructions.

Features:

• Natural language conversation with Claude AI
• Automatic tool detection and execution
• Beautiful terminal UI with the rich library
• Real-time MCP server tool testing
• Visual differentiation between Claude and MCP responses

Requirements for chat_test.py:

• Add ANTHROPIC_API_KEY to your .env file
• Ensure rich and anthropic packages are installed

Project Structure

MCP-FinTechCo/
├── server.py              # Main MCP server implementation
├── test_client.py         # Automated testing client
├── chat_test.py           # Interactive chat test utility with Claude AI
├── requirements.txt       # Python dependencies
├── .env.sample           # Environment variable template
├── .gitignore            # Git ignore patterns
├── README.md             # This file
├── CHAT_TEST_USAGE.md    # Chat test utility documentation
├── plan.md               # Project implementation plan
├── DEPLOYMENT.md         # GCP deployment guide
├── startup-script.sh     # VM initialization script
├── mcp-server.service    # Systemd service configuration
└── deploy.sh             # Deployment automation script

Configuration

The server uses environment variables for configuration. See .env.sample for all available options.

Key Environment Variables

Variable	Description	Default
ALPHA_VANTAGE_API_KEY	Alpha Vantage API key (required for market data)	-
FRED_API_KEY	FRED API key (required for economic data)	-
ANTHROPIC_API_KEY	Claude API key (required for chat_test.py)	-
MCP_SERVER_NAME	Server name	mcp-fintechco-server
MCP_SERVER_VERSION	Server version	1.0.0
MCP_SERVER_PORT	Server port	8000
LOG_LEVEL	Logging level	INFO
ENVIRONMENT	Environment name	development

Development

Adding New Financial Tools

All financial tools follow a consistent pattern separating implementation from the MCP wrapper. This allows direct testing through chat_test.py while maintaining MCP server compatibility.

Implementation Pattern:

1. Create an async implementation function with _impl suffix
2. Create an MCP tool wrapper using @mcp.tool() decorator that calls the implementation
3. Include comprehensive docstrings with parameters and examples
4. Implement error handling and logging
5. Update this README with tool documentation
6. Update chat_test.py to import and use the _impl function
7. Add tests in test_client.py

Example:

# Step 1: Implementation function (directly callable for testing)
async def get_company_overview_impl(symbol: str) -> dict:
    """Implementation of company overview retrieval."""
    if not ALPHA_VANTAGE_API_KEY:
        raise Exception("ALPHA_VANTAGE_API_KEY not configured")

    # Implementation logic here
    return {"symbol": symbol, "data": ...}

# Step 2: MCP tool wrapper (exposed to MCP clients)
@mcp.tool()
async def get_company_overview(symbol: str) -> dict:
    """
    Get fundamental company data and financial ratios.

    Args:
        symbol: Stock ticker symbol

    Returns:
        Company overview including sector, market cap, P/E ratio, etc.
    """
    return await get_company_overview_impl(symbol)

Why This Pattern?

• The @mcp.tool() decorator creates FunctionTool objects that can't be called directly
• Separating implementation allows chat_test.py to execute tools for interactive testing
• MCP server exposes the decorated versions to clients
• Same business logic, two access patterns

Testing

Run the automated test suite:

python test_client.py

For interactive testing with Claude AI:

python chat_test.py

Deployment

See DEPLOYMENT.md for detailed instructions on deploying to Google Cloud Platform.

Quick Deployment

./deploy.sh

This script automates the deployment process to GCP.

API Rate Limits

Alpha Vantage Free Tier:

• 25 API requests per day
• 5 API requests per minute
• For production use, consider upgrading to a premium plan

FRED API:

• 120 API requests per minute (shared across all IP addresses)
• 1 API request per second per IP address
• Unlimited daily requests
• Free API key registration required

For production use with high demand, consider staggering requests or using batch endpoints.

Use Cases & Combined Analysis Examples

Integrated Market-Economics Analysis

The true power of this MCP server lies in combining real-time market data (Alpha Vantage) with comprehensive economic indicators (FRED) for deeper insights:

Example 1: Employment Report Impact Analysis

"Analyze how the latest nonfarm payroll (PAYEMS) release affected the stock market.
Show me Apple stock performance over the same period and calculate RSI to see if
the market is overbought or oversold in response."

Combines: get_economic_indicator(PAYEMS) + get_stock_daily(AAPL) + get_rsi(AAPL)

Example 2: Interest Rate and Currency Correlation

"How has the USD to EUR exchange rate changed as the Federal Funds Rate (FEDFUNDS)
has been adjusted? Show recent rate changes and FX movements."

Combines: get_fx_rate(USD, EUR) + get_series_observations(FEDFUNDS)

Example 3: Inflation and Purchasing Power Analysis

"Compare inflation trends (CPI) with tech stock performance. Are tech stocks
outpacing inflation? Show me the last 24 months of both."

Combines: get_economic_indicator(CPIAUCSL) + get_stock_daily(QQQ) + get_series_observations(CPIAUCSL, units=pch)

Example 4: Fed Policy and Cryptocurrency Response

"When the Federal Funds Rate changed, how did Bitcoin respond? Show me the rate
changes and Bitcoin's price movements during the same periods."

Combines: get_crypto_rate(BTC) + get_series_observations(FEDFUNDS) + get_economic_indicator(FEDFUNDS)

Example 5: Real Estate Market Conditions

"Find housing market data (housing starts, mortgage rates). Then compare
homebuilder stock (XHB) performance to current mortgage rate trends."

Combines: get_category_series(266) (housing) + get_stock_quote(XHB) + get_economic_indicator(MORTGAGE30US)

Example 6: Sector Rotation Based on Economic Cycles

"Is unemployment rising or falling? Based on that trend, which sector is better
positioned - Technology (QQQ) or Industrials (IYJ)? Show me RSI for both."

Combines: get_economic_indicator(UNRATE) + get_rsi(QQQ) + get_rsi(IYJ)

Example 7: Leading Indicators for Market Timing

"Search for leading economic indicators. Get the recent data on initial jobless
claims and consumer confidence, then check if the S&P 500 (SPY) RSI shows
overbought/oversold conditions."

Combines: search_fred_series(leading indicators) + get_series_observations(ICSA) + get_rsi(SPY)

Traditional Use Cases

Algorithmic Trading

• Real-time market data for trading algorithms
• Technical indicators (SMA, RSI) for signal generation
• Historical data for backtesting strategies
• Economic data as macro filters for trade entry/exit

Portfolio Management

• Multi-asset portfolio tracking with real-time quotes
• Monitor economic health (GDP, unemployment) for portfolio rebalancing
• Use interest rates to model bond/equity allocation
• Risk analysis with technical indicators

Market Research & Analysis

• Historical price analysis combined with economic context
• Trend identification with SMA during different economic cycles
• Momentum analysis (RSI) vs economic expansion/contraction phases
• Understand market behavior during Fed policy changes

Economic Research & Forecasting

• Discover leading indicators that predict market downturns
• Analyze stock sector performance during economic cycles
• Monitor inflation impact on different asset classes
• Track currency movements vs monetary policy changes

Financial Applications

• Stock screeners that filter by technical indicators
• Trading dashboards that overlay economic data with price charts
• Investment analysis tools combining valuation with macro conditions
• Market data APIs for fintech startups
• Educational platforms showing market-economics relationships

Troubleshooting

Common Issues

API Key Errors:

• Verify ALPHA_VANTAGE_API_KEY is set in .env
• Check that your API key is valid
• Ensure you haven't exceeded rate limits

Server won't start:

• Verify Python version: python --version (should be 3.11+)
• Check dependencies: pip install -r requirements.txt
• Verify .env configuration

Invalid Symbol Errors:

• Use correct ticker symbols (e.g., "AAPL" not "Apple")
• Check that the symbol is traded on a supported exchange
• Verify market hours for real-time data

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Resources

• FastMCP Documentation
• FastMCP Quickstart
• Alpha Vantage API Documentation
• FRED API Documentation
• FRED Database Browser
• MCP Protocol Specification
• Technical Analysis Fundamentals
• Economic Indicators Guide

License

This project is licensed under the MIT License. See LICENSE file for details.

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing documentation
• Review FastMCP and Alpha Vantage documentation

Roadmap

Upcoming Features

• Additional Technical Indicators: EMA, MACD, Bollinger Bands, Stochastic Oscillator
• Company Fundamentals: Earnings, balance sheets, income statements
• Options Data: Real-time options chains and Greeks
• News Sentiment: Financial news and sentiment analysis
• Sector Performance: Industry and sector analytics
• Screeners: Custom stock screening capabilities
• Backtesting Tools: Historical strategy testing utilities
• Risk Metrics: VaR, Sharpe ratio, beta calculations
• Multi-Exchange Support: International market data
• WebSocket Streaming: Real-time data feeds

Acknowledgments

• Built with FastMCP 2.0
• Financial market data from Alpha Vantage
• Economic data from Federal Reserve Economic Data (FRED)
• Weather data from Open-Meteo (utility example)
• Deployed on Google Cloud Platform
• Interactive testing powered by Anthropic's Claude AI
• Tool tagging and discoverability improvements for enhanced usability

---

Version: 2.1.0 Last Updated: 2025-11-03 Primary Focus: Financial Technology & Market Data

Latest Enhancements (v2.1.0):

• Added 7 new FRED tools for tag-based discovery, release management, and data revision tracking
• Enhanced get_economic_indicator with configurable observation limit
• Improved all FRED tool docstrings with use cases and cross-references
• Comprehensive test coverage for all new tools
• FRED API coverage increased from 16% to 35%