io.github.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

Tools

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.