Overview

The Twelve Data MCP Server implements the Model Context Protocol (MCP) as a bridge between conversational agents (like Claude) and the Twelve Data market-data API. It exposes a compact set of tools that let developers and assistants request real-time quotes, historical time series, and instrument metadata (stocks, forex, crypto) using natural-language-style routing or programmatic calls.

This server is useful when you want a single, predictable MCP endpoint that handles parameter mapping, rate-limit considerations, and result formatting for Twelve Data. It supports both local deployments (for private integration) and remote/microservice setups, plus helpers for common editors and inspector tooling to speed development and debugging.

Features

Retrieve real-time quotes for equities, FX pairs, and cryptocurrencies
Fetch historical time series (OHLCV) across multiple intervals and ranges
Query instrument metadata (name, exchange, currency, asset type)
“u-tool” natural-language router to translate plain English into API calls
Integration examples for Claude Desktop and VS Code MCP clients
Debugging and inspection with the MCP Inspector utility
Deployable via pip, UV (uvx), or Docker
MIT licensed, open-source repository on GitHub

Supported asset categories (high level):

Asset type	Examples
Stocks	AAPL, TSLA, MSFT
Forex	EUR/USD, USD/JPY
Crypto	BTC/USD, ETH/USD
ETFs / Funds	SPY, QQQ

Note: exact endpoint access can depend on your Twelve Data subscription plan.

Installation / Configuration

Install and run the server locally or via a tool runner.

Using UV (recommended)

# Run the MCP server directly via uvx (no local install)
uvx mcp-server-twelve-data --help

Using pip

pip install mcp-server-twelve-data
python -m mcp_server_twelve_data --help

Docker

# Build
docker build -t mcp-server-twelve-data .

# Run with API keys
docker run --rm mcp-server-twelve-data \
  -k YOUR_TWELVE_DATA_API_KEY \
  -u YOUR_OPENAI_API_KEY \
  -t streamable-http

Obtaining your Twelve Data API key

Register at https://twelvedata.com/register
Copy the API key from your Dashboard
Note: endpoint availability and quotas depend on your subscription tier

Claude Desktop integration (example snippets)

Local stdio server with u-tool

{
  "mcpServers": {
    "twelvedata": {
      "command": "uvx",
      "args": ["mcp-server-twelve-data@latest", "-k", "YOUR_TWELVE_DATA_API_KEY", "-u", "YOUR_OPEN_AI_API_KEY"]
    }
  }
}

Remote MCP server with headers

{
  "mcpServers": {
    "twelvedata-remote": {
      "command": "npx",
      "args": [
        "mcp-remote", "https://mcp.twelvedata.com/mcp",
        "--header", "Authorization:apikey YOUR_TWELVE_DATA_API_KEY",
        "--header", "X-OpenAPI-Key:YOUR_OPENAI_API_KEY"
      ]
    }
  }
}

VS Code (User Settings JSON)

{
  "mcp": {
    "servers": {
      "twelvedata": {
        "command": "uvx",
        "args": ["mcp-server-twelve-data", "-k", "YOUR_TWELVE_DATA_API_KEY", "-u", "YOUR_OPENAI_API_KEY"]
      }
    }
  }
}

Available Tools / Resources

u-tool: a natural-language router that converts conversational requests into the right Twelve Data API calls and returns formatted results. Useful for agents or quick interactive queries.
MCP Inspector: a CLI utility to test and debug MCP servers locally. Example:

npx @modelcontextprotocol/inspector uvx mcp-server-twelve-data@latest -k YOUR_TWELVE_DATA_API_KEY

GitHub repository: https://github.com/twelvedata/mcp — source, issues, and contribution guide.
Example assets & GIFs: included in the repo to demonstrate agent interactions and editor integrations.

Use Cases

Real-time monitoring dashboard: stream or poll quotes for a watchlist (stocks, FX, crypto) and feed updates to a UI or alerting pipeline. Example command:
- Request latest quote for AAPL and USD/CAD to compare exposures.
Historical analysis and backtesting: download OHLCV series for a symbol across a specified date range and interval for indicator calculation or model training. Example: retrieve daily OHLCV for BTC/USD for the last 180 days and compute a 14-day RSI.
Research assistant in chat: connect Claude Desktop (or other MCP-capable assistants) to ask natural-language questions such as:
- “Show me Tesla intraday price and 20-period SMA for the last 5 days.”
- “Compare EUR/USD across 6 months and return percent change.”
Fundamental & metadata lookup: fetch instrument details (exchange, currency, type) when enriching a dataset or performing validation.

Debugging & Development

Use the MCP Inspector to validate server responses and see the MCP-compliant descriptors.
When iterating locally, run the server with verbose logging and use the Inspector or your editor integration (VS Code / Claude) to exercise endpoints.
The project includes a Dockerfile for consistent environments and a minimal test harness in the repo for running sample queries.

License and Contribution

This MCP server is released under the MIT License. Contributing guidelines and issue templates are available on the GitHub repository: https://github.com/twelvedata/mcp

For questions about Twelve Data product limits or pricing, consult Twelve Data documentation and your account plan.

Twelve Data MCP Server: Real-Time, Historical Market Data