Financial Skills

中文版 | English

A comprehensive financial research and analysis platform that combines a Model Context Protocol (MCP) server with intelligent orchestration skills for Claude Code and OpenCode frameworks.

Quick Start
Installation
Configuration
Usage
Troubleshooting
Project Structure
Development
Contributing
License

Quick Start

Get up and running in 5 minutes:

Prerequisites

Node.js v18 or higher
opencode or claude CLI tool
API keys from Finnhub, Alpha Vantage, TwelveData, and Tiingo (free tiers available)

Step 1: Get API Keys

Finnhub: Register at https://finnhub.io/ for free API key
Alpha Vantage: Get key at https://www.alphavantage.co/support/#api-key
TwelveData: Get key at https://twelvedata.com/pricing
Tiingo: Get key at https://www.tiingo.com/account/api/token

Step 2: Install Financial Skills

# Clone the repository
git clone https://github.com/your-org/financial-skills.git
cd financial-skills

# Set API keys (optional - will prompt if not set)
# For multiple keys, use comma-separated format: key1,key2,key3
export FINNHUB_API_KEY=your_finnhub_key
export ALPHAVANTAGE_API_KEY=your_alphavantage_key
export TWELVEDATA_API_KEY=your_twelvedata_key
export TIINGO_API_KEY=your_tiingo_key
export LOG_LEVEL=INFO

# Run the deployment script
./scripts/deploy.sh

The deployment script will:

Check for Node.js and npm
Let you select which CLI to deploy to (opencode, claude, or both)
Configure API keys and logging level in .env file
Install the MCP server and skills
Register the MCP in your CLI configuration

Step 3: Verify Installation

# Check registered MCP servers
opencode mcp list
# or
claude mcp list

You should see financial-data in the list.

Restart your IDE - all MCP servers and skills are now ready!

Step 4: Test the Setup

Try these queries to verify everything works:

Basic market data:

"What's the current price of Apple stock?"
"Compare AAPL and MSFT market cap"
"Show me Tesla's revenue for the last 4 quarters"

With web search (requires additional MCP):

"Analyze Tesla's recent performance and find news explaining price movements"
"Research NVIDIA's latest earnings and summarize analyst reactions"

Installation

Automated Installation

The deployment script (./scripts/deploy.sh) provides an interactive installation experience:

./scripts/deploy.sh

Installation flow:

Checks dependencies (Node.js, npm)
Selects target CLI (opencode, claude, or both)
Configures API keys (optional, can add later)
Installs MCP server and skills
Registers MCP in CLI configuration

Setting API Keys

API keys are optional during installation. You can:

Set via environment variables (recommended for automation):

export FINNHUB_API_KEY=your_key
export ALPHAVANTAGE_API_KEY=your_key
export TWELVEDATA_API_KEY=your_key
export TIINGO_API_KEY=your_key
./scripts/deploy.sh

Enter interactively during deployment
Add later by editing the .env file:

# For opencode
~/.opencode/mcp-servers/financial-data/.env

# For claude
~/.claude/mcp-servers/financial-data/.env

Multiple API Keys (Rotation)

For better rate limit handling, you can configure multiple API keys:

Via environment variables:

# Comma-separated keys
export FINNHUB_API_KEY=key1,key2,key3
export ALPHAVANTAGE_API_KEY=keyA,keyB,keyC
./scripts/deploy.sh

Or by editing the .env file:

FINNHUB_API_KEY=key1,key2,key3
ALPHAVANTAGE_API_KEY=keyA,keyB,keyC
TWELVEDATA_API_KEY=keyX,keyY
TIINGO_API_KEY=keyM,keyN

When multiple keys are detected, the system automatically:

Enables key rotation
Distributes requests across keys
Rotates to next key when rate limit is reached

Or use the interactive prompt during deployment - select "yes" when asked about multiple keys.

Manual Installation

If you prefer manual setup:

# 1. Copy skills (for opencode)
mkdir -p ~/.opencode/skills/
cp -r skills/financial-research ~/.opencode/skills/

# 2. Copy MCP source
mkdir -p ~/.opencode/mcp-servers/financial-data/
cp -r financial-data-mcp/* ~/.opencode/mcp-servers/financial-data/

# 3. Build and install dependencies
cd ~/.opencode/mcp-servers/financial-data/
npm install
npm run build

# 4. Create .env file with your API keys
cat > .env << EOF
FINNHUB_API_KEY=your_finnhub_key
ALPHAVANTAGE_API_KEY=your_alphavantage_key
TWELVEDATA_API_KEY=your_twelvedata_key
TIINGO_API_KEY=your_tiingo_key
LOG_LEVEL=INFO
EOF

# 5. Register MCP (if using jq)
jq --arg name financial-data \
   --arg path "$PWD/dist/server.js" \
   '.mcp[$name] = {
       type: "local",
       command: ["node", $path],
       environment: { 
         FINNHUB_API_KEY: $FINNHUB_API_KEY, 
         ALPHAVANTAGE_API_KEY: $ALPHAVANTAGE_API_KEY,
         TWELVEDATA_API_KEY: $TWELVEDATA_API_KEY,
         TIINGO_API_KEY: $TIINGO_API_KEY,
         LOG_LEVEL: "INFO"
       }
   }' ~/.config/opencode/opencode.json > /tmp/config.json && mv /tmp/config.json ~/.config/opencode/opencode.json

Installation Locations

| CLI | MCP Server | Skills | |-----|-----------|--------| | opencode | ~/.opencode/mcp-servers/financial-data/ | ~/.opencode/skills/financial-research/ | | claude | ~/.claude/mcp-servers/financial-data/ | ~/.claude/skills/financial-research/ |

Configuration

API Key Configuration

The MCP server reads API keys from the .env file in its installation directory:

Single key:

FINNHUB_API_KEY=your_api_key
ALPHAVANTAGE_API_KEY=your_api_key
TWELVEDATA_API_KEY=your_api_key
TIINGO_API_KEY=your_api_key
LOG_LEVEL=INFO

Multiple keys (comma-separated, enables rotation):

FINNHUB_API_KEY=key1,key2,key3
ALPHANTAGE_API_KEY=keyA,keyB,keyC

When multiple keys are provided, the system automatically enables key rotation.

Advanced Configuration

The .env file also supports these options:

# API Failover
API_FAILOVER_ENABLED=true
PRIMARY_API_SOURCE=finnhub
SECONDARY_API_SOURCE=alphavantage

# Retry
RETRY_ENABLED=true
RETRY_MAX_ATTEMPTS=3

# Timeout
API_TIMEOUT_MS=30000

# Circuit Breaker
CIRCUIT_BREAKER_ENABLED=true
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5

# Key Rotation (automatically enabled when multiple keys detected)
KEY_ROTATION_ENABLED=true
KEY_ROTATION_RESET_WINDOW_MS=3600000

# Logging
LOG_LEVEL=INFO  # DEBUG, INFO, WARN, ERROR

MCP Registration

The deployment script automatically registers the MCP server in your CLI configuration.

For opencode: ~/.config/opencode/opencode.json For claude: ~/.claude/settings.json

Usage

Basic Queries

Once installed, you can query financial data:

"What's Apple's current stock price?"
"Show me the revenue trend for Microsoft over the last 4 quarters"
"Compare P/E ratios of FAANG stocks"

Tool Usage Examples

Get Real-time Stock Quote

{
  "name": "get_stock_quote",
  "arguments": {
    "symbol": "AAPL"
  }
}

Get Historical Price Data

{
  "name": "get_stock_candles",
  "arguments": {
    "symbol": "MSFT",
    "resolution": "D",
    "from": "2024-01-01",
    "to": "2024-12-31"
  }
}

Get Company Information

{
  "name": "get_company_overview",
  "arguments": {
    "symbol": "GOOGL"
  }
}

Get Financial Statements

{
  "name": "get_company_metrics",
  "arguments": {
    "symbol": "TSLA",
    "metricType": "all"
  }
}

Get Technical Indicators

{
  "name": "get_technical_indicator",
  "arguments": {
    "symbol": "NVDA",
    "indicator": "RSI",
    "interval": "daily",
    "time_period": "14"
  }
}

Get Company News

{
  "name": "get_news",
  "arguments": {
    "symbol": "AAPL",
    "category": "general"
  }
}

Advanced Features

The MCP server provides these tools:

Real-time & Historical Data

get_stock_quote: Get real-time stock quote (no source parameter, auto-selected)
get_quote: Alias for get_stock_quote with optional source selection
get_stock_candles: Get historical candle/OHLCV data with time resolution

Financial Information

get_company_basic_financials: Get company financial metrics
get_company_metrics: Get company metrics (income_statement, balance_sheet, cash_flow_statement)
get_company_overview: Get company information (name, industry, sector, market cap)
get_income_statement: Get income statement
get_balance_sheet: Get balance sheet
get_cash_flow: Get cash flow statement
get_daily_prices: Get daily price history

News & Analysis

get_news: Get company news and headlines
get_technical_indicator: Get technical indicators (SMA, EMA, RSI, MACD, and 50+ more)

Additional Features

Smart Source Selection: Automatic optimal API selection for each tool
Cascading Failover: Automatic fallback to alternative sources on errors
Key Rotation: Distribute requests across multiple API keys
Debug Logging: Configurable log levels (DEBUG, INFO, WARN, ERROR)

Data Sources

| Source | Features | Free Tier | API Key | |---------|----------|-----------|----------| | Finnhub | Real-time quotes, financials, news, SEC filings | 60 calls/min (no daily limit) | Get key at finnhub.io | | Alpha Vantage | Historical prices, technical indicators, company overview | 25 calls/day (5 calls/min) | Get key at alphavantage.co | | TwelveData | Real-time quotes, historical data, technical indicators | 800 calls/day | Get key at twelvedata.com | | Tiingo | IEX quotes, EOD prices, news, fundamentals | 500 requests/hour | Get key at tiingo.com |

Smart Source Selection

The server automatically selects the optimal data source for each tool based on each platform's strengths. When a source fails (rate limit, timeout, or error), the server cascades to the next source in priority order.

Default Priority Order by Tool:

| Tool | Priority Order | |------|---------------| | get_stock_quote | Finnhub, TwelveData, Tiingo, Alpha Vantage | | get_stock_candles | TwelveData, Finnhub, Tiingo | | get_technical_indicator | TwelveData, Alpha Vantage | | get_daily_prices | Tiingo, Alpha Vantage, TwelveData | | get_news | Tiingo, Finnhub | | get_quote | TwelveData, Tiingo, Alpha Vantage | | get_company_overview | Tiingo, Alpha Vantage |

Custom Priority Override:

You can override the default priority for any tool using environment variables:

# Example: prioritize Alpha Vantage for stock quotes
SOURCE_PRIORITY_GET_STOCK_QUOTE=alphavantage,finnhub,twelvedata

# Example: use only Finnhub for news
SOURCE_PRIORITY_GET_NEWS=finnhub

Skills Available

The financial-research skill provides:

Comparative Analysis: Compare multiple companies
Trend Analysis: Analyze historical trends
News Sentiment: Analyze news impact on stock prices
Investment Reports: Generate comprehensive investment summaries

Troubleshooting

MCP Server Not Appearing

Check if MCP is registered:

opencode mcp list
# or
claude mcp list

Check the .env file:

cat ~/.opencode/mcp-servers/financial-data/.env

Check dist folder exists:

ls -la ~/.opencode/mcp-servers/financial-data/dist/server.js

Build Errors

If npm run build fails:

Ensure you're in the MCP directory
Delete node_modules and package-lock.json, then run npm install
Check Node.js version (requires v18+)

API Key Issues

Invalid API key errors:

Verify your keys at Finnhub and Alpha Vantage
Check for extra spaces in the .env file
Ensure keys don't have quotes

Rate limit errors:

Use multiple API keys (comma-separated)
Enable retry and circuit breaker options
Consider upgrading to paid API tiers

Common Issues

| Issue | Solution | |-------|----------| | MCP not connected | Restart your IDE | | "command not found" | Install Node.js v18+ | | Build fails | Run npm install in MCP directory | | Skills not loaded | Check skills directory exists |

Project Structure

financial-skills/
├── financial-data-mcp/     # MCP server source
│   ├── src/                  # TypeScript source
│   ├── dist/                 # Compiled JavaScript (pre-built)
│   ├── .env.example          # Environment template
│   └── package.json
├── skills/                    # Skills packages
│   └── financial-research/   # Main financial research skill
├── scripts/                   # Deployment scripts
│   └── deploy.sh             # Main deployment script
└── README.md                  # This file

Development

Building the MCP Server

cd financial-data-mcp
npm install
npm run build

Testing the MCP Server

cd financial-data-mcp
node dist/server.js

Then send JSON-RPC requests via stdin.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - see LICENSE file for details.