mcp

The Twelve Data MCP Server exposes Twelve Data data through the MCP (Model Context Protocol) interface, allowing Claude Desktop or other MCP clients to route natural language requests to Twelve Data endpoints via the u-tool. The server leverages u-tool to interpret English requests, select the appropriate Twelve Data API call, and return structured results such as historical time series, real-time quotes, and instrument metadata. To start using it, configure your MCP client to connect to the local uvx-based server (or the remote server) and supply your Twelve Data API key and an OpenAI API key for the routing and endpoint selection steps. Once running, you can query data like stock performance, RSI calculations, currency rates, and more through natural language commands that u-tool translates into specific Twelve Data API calls.

Key capabilities include natural language routing, endpoint selection across the Twelve Data catalog, and automatic execution of the chosen API call with properly formed parameters. The included installation options demonstrate how to run the server locally without a full codebase via uvx, or install via pip for a Python-based setup. You can also connect Claude Desktop (or other MCP clients) with preconfigured JSON snippets to point to the local server or to the Twelve Data remote endpoint. This setup aims to minimize the need to navigate Twelve Data’s 100+ endpoints by providing high-level natural language requests like “Show me Apple stock performance this week” or “Get Bitcoin RSI with a 14-day period.”

Prerequisites:

• A Twelve Data API key (required for data access).
• An OpenAI API key (required for the u-tool routing and GPT-4o orchestration).
• Optionally, Python 3.x and/or Node.js depending on the installation method you choose.

1. Using UV (recommended)

• Ensure you have uvx installed. Follow the uvx installation guide at https://docs.astral.sh/uv/guides/tools/ and install uvx.
• Run the MCP server locally:

  uvx mcp-server-twelve-data --help
  

  This will expose the Twelve Data MCP via the MCP server interface. You can customize credentials via the environment or via your MCP client configuration.

2. Using pip (Python installation)

• Install the server package:

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

• Start the server with your keys configured in your MCP client or environment:

  python -m mcp_server_twelve_data \
    -k YOUR_TWELVE_DATA_API_KEY \
    -u YOUR_OPENAI_API_KEY
  

3. Docker usage

• Build the container:

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

• Run the container with required keys:

  docker run --rm mcp-server-twelve-data \
    -k YOUR_TWELVE_DATA_API_KEY \
    -u YOUR_OPENAI_API_KEY \
    -t streamable-http
  

4. Optional: Node.js/npm-based usage (via MCP tooling or remote access)

• If you prefer an npm-based workflow for inspection or MCP tooling, you can use npx to run the remote or inspector tooling as shown in the README, but the core server runs via uvx or pip.

Tips and common issues:

• Ensure your API keys are kept secure and not exposed in public configs. Use environment variables or secure secrets management where possible.
• When using the remote Twelve Data MCP (via npx), supply correct headers for Authorization and OpenAI API key as shown in the setup examples.
• If you encounter authentication or rate-limit errors, verify your Twelve Data subscription level and that the API key is active.
• The u-tool relies on OpenAI GPT-4o; ensure your OpenAI API key has access to GPT-4o capabilities and your usage complies with OpenAI's terms.
• For Claude Desktop integration, you can either run the local stdio server with a utool-based command or point Claude to a remote MCP endpoint by configuring the JSON in claude_desktop_config.json as shown in the README.
• If you need to switch between local uvx and remote mcp-server-twelve-data, adjust the mcpServers configuration in your MCP client accordingly.
• When debugging, you can use the MCP Inspector via npx @modelcontextprotocol/inspector uvx mcp-server-twelve-data@latest -k YOUR_TWELVE_DATA_API_KEY to verify routing and parameters.