# Twelve Data MCP

> Twelve Data connects your AI agent to real-time financial markets. It gives you instant access to current stock quotes, crypto prices, forex rates, and professional technical indicators (like RSI or MACD). You can pull historical OHLCV data for any asset class—stocks, crypto, or currency pairs—and calculate complex metrics using natural language prompts.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** market-data, stock-quotes, forex, cryptocurrency, technical-indicators

## Description

When you connect your AI agent to this MCP Server, you get instant access to financial market data. This server lets you pull real-time figures and run complex analyses across stocks, crypto pairs, forex rates, and more without having to write any boilerplate code for the API calls.

To start analyzing, you need to identify what you're looking at. You can use **`search_symbols`** to broadly search for any financial instrument by filtering it by type or exchange name, or you can narrow your focus immediately. If you know you want stocks, run **`get_stock_list`**, and if crypto is the play, **`get_crypto_list`** gives you all the available pairs—you even get to filter those by exchange. For foreign currency trades, **`get_forex_list`** lists every pair available.

Once you've got your symbols locked down, you can get current pricing data fast. You use **`get_real_time_price`** when you just need the fastest possible price point for an asset. When you want a full snapshot—the open, high, low, volume, and current market price—you run **`get_quote`**. For companies, you don't have to guess; **`get_company_profile`** pulls fundamental data like the market capitalization or P/E ratio.

If you need historical context for your analysis, you pull it with **`get_time_series`**. This tool fetches OHLCV candle data for any asset across an adjustable timeframe, letting you choose intervals from one minute all the way out to a full month. You're not limited by time; you can set that range yourself.

Calculating technical indicators is where this thing really shines. Instead of manually calculating metrics, your agent runs these tools: **`get_sma`** computes the Simple Moving Average (SMA) over common periods like 20, 50, or 200 days. For something smoother, **`get_ema`** calculates the Exponential Moving Average (EMA), which gives more weight to recent price movements than older data points. You can check momentum using **`get_macd`**, which computes the Moving Average Convergence Divergence (MACD) for trend change measurement. To see if a stock is overbought or oversold, you run **`get_rsi`** to get the Relative Strength Index (RSI); it flags anything above 70 as potentially overheated or below 30 as weak. For volatility checks, **`get_bollinger_bands`** calculates Bollinger Bands, telling you if a price is way outside its normal range relative to its average. If you want to measure where the current price closed within its recent trading range, use **`get_stochastic`** for the Stochastic Oscillator; it signals extremes when prices hit 80 or drop below 20.

When your analysis involves money moving across borders, this server handles it. You can get the current exchange rate between any two currencies using **`get_exchange_rate`**, and you use **`convert_currency`** to change a specified amount from one currency into another based on those live rates.

Since most market analysis involves time series data, your agent also handles historical candle data retrieval via **`get_time_series`**. The sheer variety of tools means you don't have to switch between different API types; the whole thing runs through one connection. You can run a full-spectrum check—say, getting the 200-day SMA on a stock and comparing it against its MACD reading while also converting the resulting dollar value into Euros—all in one natural language prompt. It's powerful, man.

## Tools

### convert_currency
Converts a specified amount of money from one currency to another.

### get_bollinger_bands
Calculates Bollinger Bands, indicating if a price is overbought or oversold relative to its recent average.

### get_company_profile
Retrieves fundamental company data, such as market cap and P/E ratio.

### get_crypto_list
Lists available cryptocurrency pairs; filtering by exchange is possible.

### get_ema
Calculates the Exponential Moving Average (EMA), which weights recent price changes more heavily than older data.

### get_exchange_rate
Fetches the current exchange rate between two specified currencies.

### get_forex_list
Lists available foreign exchange (forex) trading pairs.

### get_macd
Computes the Moving Average Convergence Divergence (MACD), used to measure momentum and trend change.

### get_quote
Retrieves a comprehensive, real-time stock quote including open, high, low, volume, and current price.

### get_real_time_price
Gets only the fastest available current price for an asset; faster than a full quote.

### get_rsi
Calculates the Relative Strength Index (RSI), which signals if a stock is overbought (>70) or oversold (<30).

### get_sma
Computes the Simple Moving Average (SMA) over common periods like 20, 50, or 200 days.

### get_stochastic
Calculates the Stochastic Oscillator, measuring where a price closed relative to its recent range; signals extremes above 80 or below 20.

### get_stock_list
Searches and lists available stocks, allowing filtering by partial symbol match or exchange.

### get_time_series
Retrieves historical OHLCV candle data for a given asset across intervals from 1-minute up to 1-month.

### search_symbols
Searches broadly for financial instruments, filtering by instrument type and exchange name.

## Prompt Examples

**Prompt:** 
```
What's the current price of Apple stock?
```

**Response:** 
```
AAPL is currently trading at $192.45, up 1.23% (+$2.34) from yesterday's close. Open: $190.50, High: $193.10, Low: $189.80. Volume: 52.3M shares.
```

**Prompt:** 
```
Show me the RSI for Tesla on the daily chart.
```

**Response:** 
```
TSLA RSI (14-period) on daily chart: 58.3 — neutral territory. Not overbought (>70) or oversold (<30). The RSI has been trending upward over the past 5 sessions.
```

**Prompt:** 
```
Convert 1000 USD to EUR.
```

**Response:** 
```
1,000 USD = 921.50 EUR at the current exchange rate of 0.9215. Rate updated in real-time.
```

## Capabilities

### Retrieve Current Asset Pricing
Get real-time data points (price, volume, open/high/low) for any stock or crypto pair.

### Calculate Technical Indicators
Compute standard metrics like SMA, RSI, MACD, and Bollinger Bands from historical price movements.

### Analyze Historical Time Series
Fetch OHLCV candlestick data across adjustable time intervals (1-minute to 1-month).

### Manage Currency Conversions
Exchange amounts between any two currencies using current market rates.

### Identify Financial Instruments
Search and list available assets, including stocks, crypto pairs, and forex instruments.

## Use Cases

### Identifying optimal entry points for crypto trading
A trader notices Bitcoin price movement but isn't sure when it's safe to buy. They ask their agent: 'Show me BTC-USD’s RSI and MACD over the last two weeks.' The agent calls `get_rsi` and `get_macd`, providing both indicators so the user can confirm if the market is oversold or trending upward before initiating a trade.

### Assessing stock health for an investment thesis
A research analyst needs to check Apple (AAPL). They first use `get_company_profile` to review fundamental metrics like P/E ratio. Then, they call `get_time_series` to pull historical OHLCV data, which they feed into the agent for running an SMA comparison against its current price.

### Comparing global portfolio performance
A fund manager needs to check a mixed portfolio: EUR/USD and Tesla stock. They ask the agent: 'What was the exchange rate last Tuesday, and what was TSLA's closing quote?' The agent executes `get_exchange_rate` and `get_quote`, giving immediate, multi-asset context.

### Backtesting a strategy on forex pairs
A quant needs to validate a trading signal for GBP/JPY. They request historical data via `get_time_series` (setting the interval and date range), which allows them to run indicators like Bollinger Bands and check if the price touched an extreme band during the test period.

## Benefits

- **Deep Indicator Analysis:** Instead of manually calculating metrics, use tools like `get_rsi` or `get_macd`. Your agent runs these complex calculations on demand, telling you immediately if an asset is overbought or signaling a momentum shift. This saves hours of spreadsheet work.
- **Comprehensive Data Scope:** You don't just get prices; you get the full picture. With tools like `get_company_profile`, your AI client pulls fundamental data (P/E, market cap) alongside technical indicators, giving context to every price movement.
- **Flexible Time Series Retrieval:** Need 1-hour candles for backtesting? Or monthly closes for macro trends? The `get_time_series` tool handles it. It gives you OHLCV data across a massive range of intervals (1min to 1month) in one call.
- **Cross-Asset Comparison:** Stop switching between separate platforms. Use the server to compare assets—say, comparing AAPL's SMA vs. BTC's MACD—all within your single AI prompt, covering stocks, crypto, and forex pairs.
- **Currency Agnostic Workflows:** No matter where your analysis takes you, `get_exchange_rate` and `convert_currency` handle the math for you. You can run a global portfolio check and get everything normalized to USD instantly.

## How It Works

The bottom line is you tell your AI client what market data you need, and it executes the necessary API calls through the appropriate specialized tool.

1. Subscribe to the Twelve Data server on Vinkius Marketplace.
2. Input your personal Twelve Data API Key into the client configuration.
3. Ask your AI agent a financial question (e.g., 'Compare AAPL's RSI to MSFT's MACD over the last 30 days'). The agent translates this request into specific tool calls.

## Frequently Asked Questions

**How do I get real-time prices using get_real_time_price?**
You ask your agent to use `get_real_time_price` and specify the symbol (e.g., AAPL). It returns only the fastest available current price, which is ideal for quick checks when you don't need volume or high/low data.

**Can I run MACD on crypto pairs?**
Yes. You can use `get_macd` by specifying a supported cryptocurrency pair (e.g., BTC-USD) and the required time series for the calculation, letting you analyze its momentum.

**Which tool is better: get_quote or get_real_time_price?**
Use `get_quote` when you need a full snapshot of the stock—it includes open, high, low, and volume. Use `get_real_time_price` only if speed is your absolute priority and you don't care about the other metrics.

**How do I find which forex pairs are available?**
Run the `get_forex_list` tool. This returns a comprehensive list of all supported foreign exchange trading pairs, letting you know exactly what assets you can analyze.

**How do I set up my API key when using get_quote?**
You must provide your Twelve Data API key during the initial connection phase. Your AI client handles passing this key securely for all requests, so you don't need to manage it manually.

**What time intervals are supported by get_time_series?**
The tool supports retrieving OHLCV candle data ranging from 1-minute up to 1-month intervals. You specify the exact frequency you need in the function's input parameters.

**Does get_rsi allow me to change the lookback period?**
Yes, you define the required lookback period in the request arguments. While 14 periods is common for RSI analysis, adjusting this number lets you tailor the indicator to specific market views.

**What happens if I call multiple tools too quickly, like get_quote and get_company_profile?**
The server enforces standard API rate limits. If you exceed these limits, expect an HTTP 429 error. Simply wait a short period before retrying the function calls.

**How do I get a Twelve Data API Key?**
Visit [**Twelve Data**](https://twelvedata.com/), sign up for a free account, and copy your API key from the dashboard. Free tier includes 800 API credits/day.

**What technical indicators are available?**
SMA (Simple Moving Average), EMA (Exponential MA), RSI (Relative Strength Index), MACD, Bollinger Bands, and Stochastic Oscillator — all with customizable periods.

**Can I get real-time crypto and forex prices?**
Yes! Use `get_quote` or `get_real_time_price` with any symbol. Crypto pairs like BTC/USD and forex pairs like EUR/USD are supported.