mcp

# Synergic APIs — MCP Server

Official [Model Context Protocol](https://modelcontextprotocol.io) server for
[Synergic APIs](https://synergicapis.com): official US economic data for AI
agents. It gives Claude, Cursor, and any MCP-capable client direct access to:

- **US Inflation API** — the official CPI-U from the Bureau of Labor Statistics:
  11 categories, YoY/MoM rates computed like the BLS, monthly history back to
  **1913**, official annual averages.
- **Famous prices** — US average price of eggs, gasoline, milk, bread, ground
  beef, coffee and electricity, monthly since 1976.
- **US National Debt API** — the U.S. Treasury debt to the penny, every business
  day since 1993, annual debt outstanding since **1790**, and the average
  interest rates the Treasury pays.

All amounts are JSON numbers, periods are `YYYY-MM` / `YYYY-MM-DD`, and missing
months in the official record are served as `null` — never invented.

## Requirements

- Node.js 18.17+ (`npx` included).
- A Synergic APIs key. **Get one free (no credit card) at
  [synergicapis.com/signup.html](https://synergicapis.com/signup.html)** —
  500 requests/month, both APIs, full history. Paid plans at
  [synergicapis.com/pricing.html](https://synergicapis.com/pricing.html).

## Installation

The server runs over stdio via `npx` — no clone, no build.

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "synergic-apis": {
      "command": "npx",
      "args": ["-y", "@synergic-apis/mcp"],
      "env": {
        "SYNERGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add synergic-apis --env SYNERGIC_API_KEY=YOUR_API_KEY -- npx -y @synergic-apis/mcp
```

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project):

```json
{
  "mcpServers": {
    "synergic-apis": {
      "command": "npx",
      "args": ["-y", "@synergic-apis/mcp"],
      "env": {
        "SYNERGIC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Configuration

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `SYNERGIC_API_KEY` | yes | — | Your API key. Sent as `X-Api-Key` on every request. |
| `SYNERGIC_GATEWAY_URL` | no | `https://api.synergicapis.com` | Gateway base URL (override for testing). |

## Tools

| Tool | What it does | Key arguments |
| --- | --- | --- |
| `get_us_inflation_latest` | Latest month of CPI for all 11 categories with YoY/MoM rates. | `adjusted` (optional) |
| `get_us_inflation_history` | Monthly CPI history of one category (headline since 1913). | `category`, `start`/`end` (`YYYY-MM`), `limit` (≤100), `adjusted` |
| `get_us_inflation_annual` | Official annual average CPI (M13, NSA). `limit=150` = whole headline series. | `category`, `start`/`end` (`YYYY`), `limit` (≤150) |
| `get_famous_prices` | Latest basket of famous US prices, or one item's monthly history. | `item` (optional), `start`/`end` (`YYYY-MM`), `limit` (≤100) |
| `get_us_debt_latest` | The US national debt today, to the penny. | — |
| `get_us_debt_history` | Daily debt (1993+, limit ≤100) or annual fiscal-year-end debt (1790+, `limit=250` = whole series). | `frequency` (`daily`/`annual`), `start`/`end` (`YYYY-MM-DD`), `limit` |
| `get_us_interest_rates` | Latest Treasury avg interest rate per security class, or one class's monthly history (2001+). | `security_class` (optional), `start`/`end` (`YYYY-MM-DD`), `limit` (≤100) |
| `get_my_usage` | Plan, requests used, monthly limit and reset date of your key. | — |

History tools paginate by period range: when a response's `meta.next_end` is not
`null`, call the tool again with `end` set to that value to get older data.

## Try it

Ask your assistant things like:

- *"What is US inflation right now, headline and core?"*
- *"Plot the price of eggs since 2020."*
- *"How much did the US national debt grow in the last 12 months?"*
- *"What rate does the Treasury pay on T-bills today vs 2021?"*

## Troubleshooting

- **"SYNERGIC_API_KEY is not set"** — the server exits at startup if the key is
  missing. Add it to the `env` block of your MCP client config (see above) and
  restart the client.
- **"Invalid API key"** — the gateway rejected the key (typo or revoked). Keys
  look like `sk_...`. Get a fresh one at
  [synergicapis.com/signup.html](https://synergicapis.com/signup.html).
- **"Rate limit exceeded … retry after Xs"** — you hit your plan's per-minute
  limit (free: 10 req/min). Wait and retry.
- **"Monthly quota exhausted"** — you used the month's requests (free: 500).
  Ask the agent to call `get_my_usage` for details, wait for the 1st (UTC), or
  upgrade at [synergicapis.com/pricing.html](https://synergicapis.com/pricing.html).
- **Tools don't appear in the client** — check the client's MCP logs; the most
  common causes are an old Node (needs 18.17+) or `npx` not on the PATH used by
  the client. Running `npx -y @synergic-apis/mcp` in a terminal should print
  `ready on stdio` to stderr and then wait for input.
- **Corporate proxy / self-hosted testing** — point `SYNERGIC_GATEWAY_URL` at
  your gateway; the server only ever issues GET requests with `X-Api-Key`.

## Development

```bash
npm install
npm run typecheck   # tsc --noEmit (strict)
npm test            # vitest — tool→request mapping + error mapping, fetch mocked
npm run build       # emits dist/ and the synergic-apis-mcp bin
```

## Data sources & license

Data: U.S. Bureau of Labor Statistics and U.S. Treasury Fiscal Data (public
domain; this product is not endorsed by or affiliated with either agency).
Code: MIT.