# New York Fed MCP Server

A Model Context Protocol (MCP) server for accessing Federal Reserve Bank of New York Markets Data APIs. This server provides standardized access to financial market data including reference rates, SOMA holdings, Treasury operations, and more.

## Features

This MCP server provides access to the following New York Fed data:

### 📊 Reference Rates
- **All Reference Rates**: SOFR, EFFR, OBFR, TGCR, BGCR in one request
- **Secured Rates**: SOFR (Secured Overnight Financing Rate), TGCR, BGCR
- **Unsecured Rates**: EFFR (Effective Federal Funds Rate), OBFR

### 🏦 System Open Market Account (SOMA) Holdings
- Treasury securities holdings (Bills, Notes/Bonds, FRN, TIPS)
- Agency securities holdings (Agency Debts, MBS, CMBS)
- Holdings by date, CUSIP, or holding type
- Summary data and historical information

### 💼 Market Operations
- **Treasury Operations**: Purchases, sales, and prices paid
- **Repo Operations**: Repo and reverse repo operations
- **Primary Dealer Statistics**: Survey data and market share information

### 📈 Data Formats
All endpoints support multiple formats:
- JSON (default)
- XML
- CSV
- PDF
- Excel (XLSX)

## Installation

### Option 1: Via NPM/NPX (Recommended)

The easiest way to use this server is via npx:

```bash
npx @trygordian/mcp-newyorkfed
```

### Option 2: From Source

1. Clone this repository:
```bash
git clone https://github.com/trygordian/mcp-newyorkfed.git
cd mcp-newyorkfed
```

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

3. Build the project:
```bash
npm run build
```

## Usage

### As an MCP Server

The server implements the Model Context Protocol and can be used with any MCP-compatible client.

#### Configuration for MCP clients:

**Using NPX (Recommended):**
```json
{
  "mcpServers": {
    "newyorkfed": {
      "command": "npx",
      "args": [
        "-y",
        "@trygordian/mcp-newyorkfed"
      ]
    }
  }
}
```

**Using Local Installation:**
```json
{
  "mcpServers": {
    "newyorkfed": {
      "command": "node",
      "args": ["path/to/mcp-newyorkfed/build/index.js"]
    }
  }
}
```

#### Running the server directly:
```bash
# Via NPX
npx @trygordian/mcp-newyorkfed

# Via NPM (if installed globally)
npm install -g @trygordian/mcp-newyorkfed
mcp-newyorkfed

# From source
npm start
# or
node build/index.js
```

## Available Tools

### 1. `get_reference_rates_all`
Get all reference rates for the latest date or search with filters.

**Parameters:**
- `operation`: "latest" | "search"
- `format`: "json" | "xml" | "csv" | "pdf" | "xlsx"
- `startDate`: Start date for search (YYYY-MM-DD)
- `endDate`: End date for search (YYYY-MM-DD)

**Example:**
```json
{
  "operation": "latest",
  "format": "json"
}
```

### 2. `get_secured_rates`
Get secured reference rates (SOFR, TGCR, BGCR).

**Parameters:**
- `operation`: "latest" | "last" | "search"
- `rateType`: "sofr" | "tgcr" | "bgcr" (required for last/search)
- `number`: Number of records (1-1000, for "last" operation)
- `format`: Response format
- `startDate`/`endDate`: Date range for search

**Example:**
```json
{
  "operation": "last",
  "rateType": "sofr",
  "number": 30,
  "format": "json"
}
```

### 3. `get_unsecured_rates`
Get unsecured reference rates (EFFR, OBFR).

**Parameters:**
- `operation`: "latest" | "last" | "search"
- `rateType`: "effr" | "obfr" (required for last/search)
- `number`: Number of records (1-1000, for "last" operation)
- `format`: Response format
- `startDate`/`endDate`: Date range for search

### 4. `get_soma_holdings`
Get System Open Market Account holdings data.

**Parameters:**
- `operation`: "summary" | "latest_date" | "list_dates" | "treasury_by_date" | "agency_by_date" | "treasury_by_cusip" | "agency_by_cusip"
- `format`: Response format
- `date`: As-of date (YYYY-MM-DD, required for *_by_date operations)
- `cusip`: CUSIP identifier (required for *_by_cusip operations)
- `holdingType`: "bills" | "notesbonds" | "frn" | "tips" | "agency debts" | "mbs" | "cmbs"

**Example:**
```json
{
  "operation": "treasury_by_date",
  "date": "2024-01-15",
  "holdingType": "bills",
  "format": "json"
}
```

### 5. `get_treasury_operations`
Get Treasury securities operations.

**Parameters:**
- `operation`: "purchases" | "sales"
- `timeframe`: "latest" | "lastTwoWeeks" | "last"
- `status`: "all" | "completed" (required for latest)
- `include`: "details" | "summary"
- `number`: Number of operations (for "last" timeframe)
- `format`: Response format
- `startDate`/`endDate`: Date range

### 6. `get_repo_operations`
Get repo and reverse repo operations.

**Parameters:**
- `operationType`: "repo" | "reverserepo"
- `method`: "all" | "single-tranche" | "multiple-price"
- `timeframe`: "latest" | "lastTwoWeeks" | "last" | "search"
- `status`: "all" | "completed" (required for latest)
- `number`: Number of operations (for "last" timeframe)
- `format`: Response format
- `startDate`/`endDate`: Date range for search

### 7. `get_primary_dealer_statistics`
Get Primary Dealer Statistics survey data.

**Parameters:**
- `operation`: "latest_by_series" | "all_surveys" | "list_timeseries" | "list_dates" | "list_series_breaks" | "by_date" | "by_timeseries" | "by_series_and_timeseries"
- `seriesBreak`: Series break identifier
- `date`: As-of date (YYYY-MM-DD)
- `timeseries`: Time series/key ID
- `format`: Response format

### 8. `get_market_share`
Get Primary Dealer market share data.

**Parameters:**
- `period`: "quarterly" | "ytd"
- `format`: Response format

## API Data Sources

This server provides access to data from the Federal Reserve Bank of New York's Markets Data APIs:
- Base URL: `https://markets.newyorkfed.org`
- Documentation: [NY Fed Markets API Documentation](https://markets.newyorkfed.org/static/docs/markets-api.html)

## Legal Notice

Use of reference rates, the Markets Data APIs, and all data accessible through the Markets Data APIs is subject to the [Terms of Use](https://www.newyorkfed.org/privacy/termsofuse) for the Federal Reserve Bank of New York website.

Reference rates are subject to important disclaimers, conditions, limitations, and indemnification obligations described in the Terms of Use.

## Error Handling

The server provides comprehensive error handling:
- Invalid parameters return detailed error messages
- API failures include HTTP status codes and error descriptions
- Missing required parameters are clearly identified

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues related to:
- **This MCP server**: Open an issue in this repository
- **NY Fed API data**: Contact the Federal Reserve Bank of New York
- **MCP protocol**: See the [Model Context Protocol documentation](https://modelcontextprotocol.io/)

---

**Disclaimer**: This is an unofficial implementation. The Federal Reserve Bank of New York is not responsible for this server or its functionality.