# Stock Trade MCP Server

A Model Context Protocol (MCP) server that exposes various [Tiingo API](https://www.tiingo.com/documentation/general/overview) endpoints as tools. This server allows programmatic access to financial data including stock prices, news, forex, fundamentals, and corporate actions via the MCP protocol.

## Prerequisites

- Node.js (v18 or later recommended)
- npm (comes with Node.js)
- A Tiingo API Key
- MCP-compatible client or runner (e.g., VSCode extension, CLI)

## Setup

1.  **Clone the repository or ensure you are in the project directory.**

2.  **Install dependencies:**
    ```bash
    npm install
    ```

3.  **Obtain Your Tiingo API Key:**
    To use this server, you need a Tiingo API token.
    1.  Register for a Tiingo account if you don't have one.
    2.  Go to your Tiingo Account page and navigate to the API Token section (or directly visit: https://www.tiingo.com/account/api/token).
    3.  Copy your API Token. You will need to provide this token to your MCP client to authenticate with the Tiingo API.
*Note: Programmatic registration or logins are not supported by Tiingo; the API token is the sole method for authentication.*

4.  **Set Tiingo API Key:**
    This server requires your Tiingo API key. You can typically provide the API key in your MCP client's configuration (see "Running the Server" below for an example).

5.  **Build the server:**
    ```bash
    npm run build
    ```
    This will create a `build` directory with the compiled JavaScript code.

## Running the Server

- **Via MCP runner:**
  Configure your MCP client to run the server using stdio transport. You can provide the `TIINGO_API_TOKEN` in the `env` block of the configuration.
  Example MCP settings entry:
  ```json
  "mcp-tiingo": {
    "transportType": "stdio",
    "command": "node",
    "args": [
      "/path/to/mcp-tiingo/build/index.js"
    ],
    "env": {
      "TIINGO_API_TOKEN": "YOUR_API_KEY_HERE"
    }
    // ... other optional settings ...
  }
  ```
  *(Replace `/path/to/mcp-tiingo` and `YOUR_API_KEY_HERE` accordingly)*

## Available Tools

The server exposes the following Tiingo API endpoints as tools via MCP:

### **get_end_of_day_prices**
- **Description:** Fetches End-of-Day prices for a given ticker symbol with optional date range and format.
- **Key Inputs:** `ticker`, `startDate`, `endDate`, `resampleFreq`

### **get_news**
- **Description:** Fetches news articles from Tiingo with various filtering options.
- **Key Inputs:** `tickers`, `tags`, `sources`, `startDate`, `endDate`, `limit`

### **get_forex_prices**
- **Description:** Fetches historical intraday Forex prices for a given ticker symbol with optional date range and frequency.
- **Key Inputs:** `ticker`, `startDate`, `endDate`, `resampleFreq`

### **get_forex_top_of_book**
- **Description:** Fetches real-time Forex Top-of-Book/Last data for one or more ticker symbols.
- **Key Inputs:** `ticker` or `tickers`

### **get_fundamentals_definitions**
- **Description:** Fetches available fundamental metrics and their definitions.
- **Key Inputs:** None

### **get_fundamentals_statements**
- **Description:** Fetches historical fundamental statement data (Balance Sheet, Income Statement, Cash Flow, Overview) for a given ticker.
- **Key Inputs:** `ticker`, `startDate`, `endDate`, `year`, `quarter`

### **get_fundamentals_daily_metrics**
- **Description:** Fetches daily fundamental metrics for a given ticker.
- **Key Inputs:** `ticker`, `startDate`, `endDate`, `columns`

### **get_fundamentals_meta**
- **Description:** Fetches fundamental meta data for companies.
- **Key Inputs:** None

### **get_dividend_distributions**
- **Description:** Fetches historical dividend and distribution data for a given ticker.
- **Key Inputs:** `ticker`, `startExDate`, `endExDate`

### **get_dividend_yield**
- **Description:** Fetches historical dividend yield data for a given ticker.
- **Key Inputs:** `ticker`, `startDate`, `endDate`, `columns`

### **get_splits**
- **Description:** Fetches historical split data for a given ticker.
- **Key Inputs:** `ticker`, `startExDate`, `endExDate`

## Extending

To add more Tiingo API endpoints as tools:
1. Create a new TypeScript file in `src/tools/` defining the tool's name, description, input schema (using Zod), and handler function to call the Tiingo API.
2. Import and add the tool definition object to the `tiingoTools` array in `src/tools/index.ts`.
3. Rebuild the server (`npm run build`).