@synergic-apis/mcp

Synergic APIs — MCP Server

Official Model Context Protocol server for Synergic APIs: 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 — 500 requests/month, both APIs, full history. Paid plans at 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):

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

Claude Code

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):

{
  "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.
• "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.
• 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

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.