fundafx-mcp-server

v0.4.4

Published

20 days ago

FundaFX MCP Server - FX Fundamental Data for AI Agents. Provides forex fundamental analysis data (facts, indicators, central bank rates) via the Model Context Protocol.

0High
0Medium
0Low

sinnikomaru

mcp fundafx forex fx fundamental-analysis model-context-protocol ai-agents

FundaFX MCP Server

Bring FundaFX — a 12-source FX fundamentals database — into Claude, Cursor, Windsurf, or any MCP-compatible client.

🏠 Website: fundafx.link
📖 Full setup guide: fundafx.link/mcp.html
📱 Mobile app: App Store · Google Play (coming soon)

What is FundaFX?

FundaFX is an FX fundamentals service that consolidates economic data, central-bank decisions, and institutional releases from 12 authoritative sources (ECB, Federal Reserve, OECD, World Bank, e-Stat, EIA, CFTC, GDELT, Treasury, FRB / Central-Bank / News RSS, X / Twitter) and serves them through an AI-agent-friendly API.

The MCP server on this page is the thin adapter that exposes the FundaFX REST API to LLM agents (Claude, GPT, etc.) via the Model Context Protocol, so you can ask questions like "show me the next FOMC meeting date" or "give me the latest USD high-importance facts" in natural language.

How the pieces fit together

┌──────────────────────────────────────────────────────────┐
│  How to get an API key                                   │
│                                                          │
│  Option A: Web (fastest)                                 │
│    fundafx.link/access → email → magic link → copy key   │
│                                                          │
│  Option B: Mobile app (required for Pro subscription)    │
│    iOS / Android app → Settings → API Key Management     │
└──────────────────────────────┬───────────────────────────┘
                               │ issues
                               ▼
                         ┌──────────┐
                         │ API key  │
                         └─────┬────┘
                               │ used by
                               ▼
               ┌───────────────────────────┐
               │  FundaFX MCP Server       │  ← this package
               │  (npm: fundafx-mcp-server)│
               └──────────┬────────────────┘
                           │ speaks MCP to
                           ▼
         Claude Desktop / Claude Code / Cursor / Windsurf / ...

Prerequisites

1. FundaFX API key — required

You can obtain an API key in two ways:

Option A: Web (fastest, recommended for developers)

Visit fundafx.link/access
Enter your email → click the magic link → copy the fndx_… key from the dashboard
Free tier (100 requests/month) is provisioned automatically

Option B: Mobile app (required for Pro subscription)

Install FundaFX from the App Store (id6761375247)
Open Settings → API Key Management → copy the fndx_… key
Free tier (100/month) is provisioned automatically; Pro tier (5,000/month) is also available

| Tier | Web (access page) | Mobile app | |------|-------------------|------------| | Free (100 req/month) | ✅ | ✅ | | Pro (5,000 req/month) | — (coming soon) | ✅ |

2. Node.js 20 or later

npx fundafx-mcp-server is invoked by your MCP client at runtime, so a recent Node.js runtime must be available on your machine.

Quick start

Step 1 — Get your API key

Option A (web — fastest): Visit fundafx.link/access, enter your email, click the magic link, and copy the fndx_… key from the dashboard.

Option B (mobile app): Install FundaFX from the App Store (see link above), then open Settings → API Key Management and copy the fndx_ key.

Step 2 — Register the MCP server in your client

Claude Desktop (JSON configuration)

Edit the Claude Desktop config file:

| OS | Path | |----|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

Add a fundafx entry under mcpServers:

{
  "mcpServers": {
    "fundafx": {
      "command": "npx",
      "args": ["fundafx-mcp-server"],
      "env": {
        "FUNDAFX_API_KEY": "fndx_your_api_key_here",
        "FUNDAFX_API_URL": "https://api.fundafx.link"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code (CLI command)

claude mcp add fundafx \
  --scope user \
  --env FUNDAFX_API_KEY=fndx_your_api_key_here \
  --env FUNDAFX_API_URL=https://api.fundafx.link \
  -- npx fundafx-mcp-server

Verify with claude mcp list — the entry should show ✓ Connected.

Cursor / Windsurf / other MCP clients

Any MCP-compatible client accepts the same JSON shown for Claude Desktop above. Paste it into the client's MCP configuration panel.

Step 3 — Ask your agent a question

"What's the current FED policy rate and when is the next FOMC meeting?" "Show me the latest high-importance USD facts." "Compare the interest-rate differentials between USD and JPY."

Your agent will pick the right tool automatically.

Tools

The server exposes 4 tools. Historical time-series data is retrieved through get_indicator_analysis with include_history=true (not a separate tool).

| Tool | What it does | |------|--------------| | get_facts | Retrieve recent fundamental FX facts (institutional releases, official speeches, media reports) | | get_indicator_analysis | Detailed analysis of one economic indicator (+ optional history) | | get_central_bank_sentiment | Central bank policy snapshot (current rate, next meeting, governor, metadata) | | get_rate_differentials | Interest-rate differentials across currency pairs (carry-trade analysis) |

Note (v0.4.3 — bias-correction layer): get_facts accepts a new distinct_source boolean parameter that collapses the result to one row per source_name (most recent event_timestamp wins). The formatted footer always renders a per-source distribution one-liner regardless of the flag:
📊 Source distribution / ソース分布: twitter:IranIntl_En (18件), gdelt (4件), twitter:Bank_of_Japan_j (1件), news_rss:reuters (1件), news_rss:bloomberg (1件)
When distinct_source=true is enabled, an additional summary line reports the collapse: 🧹 distinct_source=true でソース連投を排除 (元 25件 → 5件). Use this when one Twitter handle dominates the high-importance hits (e.g. an Iran International account posting 18 of 25 facts in one day) and you want a coverage view rather than a volume view. PBI-20260510-007.
Note (v0.4.2 — narrative time-series access): get_facts default date_from is now 90 days (was 14d in v0.4.1), the limit ceiling rises to 500, and a new as_of parameter lets agents query the corpus as it stood at a historical moment ("what did FundaFX know about by 2026-04-15?"). The formatted footer carries an LLM-friendly one-liner
取得期間 / Coverage: 2026-02-10 ~ 2026-05-10 / 47件 / 12 distinct source(s)
plus the corpus-wide block (from_date / to_date / as_of / total_count / distinct_source_count). Agents can spot single-source echo chambers (e.g. distinct=1, total=47 → likely a Twitter chain) and low-data windows in a single read. PBI-20260510-006.
Note (v0.4.1): get_facts defaulted date_from to 14 days before the current UTC time and the response footer carried a Coverage window block with earliest/latest event_timestamp + truncated-by-limit signal. v0.4.2 supersedes the 14d default with 90d.
Note (v0.4.0): get_facts now supports date_from / date_to (ISO 8601) for date-range filtering and surfaces the original source URL(s) of each fact in the formatted output. The REST envelope already exposed source_urls; v0.4.0 just renders them in the MCP-formatted response.
Note (v0.3.0): hawkish/dovish NLP sentiment scoring was removed in v0.3.0 (was added in v0.2.0). See the project's removal ADR for context. The get_central_bank_sentiment tool now returns institution overview only (rate, next meeting, governor) — same shape as v0.1.x.

`get_facts`

Filters facts by currency, type, importance, collector, and date range. The response includes the original source URL(s) for each fact, so you can always trace a fact back to the primary publication.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | currency | string | No | USD, EUR, JPY, GBP, AUD, NZD, CAD, CHF, MXN, SEK, NOK, ZAR, KRW, INR, TRY, CNY, BRL, SGD, HKD, THB, PLN (21 currencies) | | fact_type | string | No | institutional_release, official_speech, media_report, institutional_notification | | importance | string | No | high, medium, low | | source_collector | string | No | cb_rss, ecb, gdelt, news_rss, … | | date_from | string (ISO 8601) | No | Filter facts with event_timestamp >= date_from (e.g. 2026-03-01T00:00:00Z). Defaults to 90 days before the current UTC time when omitted (v0.4.2+). For event-study, quarterly review, or intervention analyses extend the window further. | | date_to | string (ISO 8601) | No | Filter facts with event_timestamp <= date_to (e.g. 2026-03-31T23:59:59Z). | | as_of | string (ISO 8601) | No | Historical-snapshot anchor (v0.4.2+). When supplied, the result is restricted to facts whose created_at <= as_of — i.e. "what did FundaFX know about at this exact moment?". Useful for narrative time-series and PIT-style backtests. Future timestamps are rejected (422). | | distinct_source | boolean | No | Source-bias correction (v0.4.3+). When true, collapse the result so each source_name appears at most once — keeping the most recent row per source. Use this to neutralise single-account chains (e.g. an Iran International twitter handle posting 18 of 25 high-importance facts). The footer always reports the uncollapsed distribution so callers can see what was hidden. | | limit | number | No | 1–500 (default 50; v0.4.2 raised the ceiling 100 → 500 so 90d windows fit one round-trip) |

Note: Facts from BOE (Bank of England) and SNB (Swiss National Bank) use a fact-notification format (fact_type: "institutional_notification") that does not include body text or summaries (compliance with non-commercial distribution licenses). The source_url always points to the original publication for full content.

Example prompts:

"Get the latest high-importance USD facts." (uses 90d default)
"Show me all USD facts between 2026-03-01 and 2026-03-31."
Narrative time-series: "Walk me through the JPY intervention period 2026-04-25 ~ 2026-05-05 — show every fact, in order." (use date_from / date_to)
Historical snapshot (PIT-style): "What facts had FundaFX ingested about USD by 2026-04-15? — give me a single-source diversity check for that window." (set as_of=2026-04-15T00:00:00Z; check coverage_window.distinct_source_count in the footer to spot single-source echo chambers)
Quarterly review: "Summarise EUR monetary-policy facts for the last quarter and tell me whether the corpus is dominated by one source." (use 90d default + filter by currency=EUR & category=monetary_policy; the footer's total_count and distinct_source_count answer the diversity question)
Bias-corrected high-importance scan (v0.4.3+): "Show me the high-importance JPY facts from the last 7 days, but de-duplicate any Twitter handle that posted more than once — I don't want a single account dominating the picture." (set currency=JPY & importance=high & distinct_source=true; the footer shows 元 25件 → 5件にソース連投を排除 and the original distribution so the LLM still sees that IranIntl_En posted 18 of the 25 raw hits)

`get_indicator_analysis`

Returns metadata and the latest value for one indicator. Pass include_history=true to also get historical data points.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | indicator | string | Yes | Indicator code in <COUNTRY>_<INDICATOR> format (e.g. US_CPI, US_NFP, US_UNEMPLOYMENT, JP_GDP, EU_HICP, GB_CPI). Unknown codes return the full catalogue in the error message. | | include_history | boolean | No | Include historical data points (default false) | | as_of | string (ISO 8601) | No | Point-in-time query — returns the value as observed at this timestamp (e.g. 2026-04-01T00:00:00Z for backtesting). Returns the latest value if omitted. |

Example prompt: "Analyze the US CPI indicator with historical data."

`get_central_bank_sentiment`

Returns the institution overview for a central bank: current policy rate, next meeting date, governor, and additional metadata.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | bank | string | Yes | FED, ECB, BOJ, BOE, RBA, BOC, SNB, RBNZ, PBOC |

Example prompt: "What's the FED current policy rate and next meeting date?"

`get_rate_differentials`

Cross-section of central-bank policy rates and their spreads.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | base | string | No | Base currency (USD, EUR, JPY, GBP, AUD, NZD, CAD, CHF, CNY). Omit for all. | | quote | string | No | Quote currency (same set as above). Omit for all. |

Example prompt: "Show the rate differential between USD and JPY."

Rate limits & pricing

| Tier | Monthly requests | How to get it | |------|------------------|---------------| | Free | 100 | Web (fundafx.link/access) or mobile app — key issued automatically | | Pro | 5,000 | Subscribe to FundaFX Pro inside the mobile app |

Limits apply across all API traffic, including MCP calls. Counters reset on the first of each month.

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | FUNDAFX_API_KEY | Yes | — | API key (fndx_…) — get it via fundafx.link/access or the mobile app | | FUNDAFX_API_URL | No | https://api.fundafx.link | Override only if you run your own FundaFX API instance |

Data sources

12 authoritative sources:

ECB · Federal Reserve · Bank of Japan (RSS) · Bank of England (RSS) · OECD · World Bank · e-Stat (Japan) · EIA (US energy) · CFTC (COT) · GDELT · Treasury Yields · X / Twitter (official accounts)

See the landing page for the full list and data types.

Troubleshooting

401 Unauthorized — The FUNDAFX_API_KEY is missing or has been revoked. Reissue it from the web dashboard (fundafx.link/access) or the mobile app (Settings → API Key Management → Reissue).
Indicator not found: "XXX" — The error response contains the full catalogue of valid indicator codes. Copy one and retry.
Tool list is empty in Claude / Cursor / Windsurf — Restart the MCP client. Config changes only take effect on restart.
✗ Failed to connect in claude mcp list — Make sure Node.js 20+ is installed and npx is on your PATH.

Contributing / local development

The rest of this section is for contributors working on the MCP server itself. End users do not need any of this.

Architecture

mcp-server/
  src/
    index.ts          Entry point (stdio transport)
    server.ts         MCP server factory (tool registration)
    api_client.ts     HTTP client for the FundaFX REST API
    types.ts          TypeScript types mirroring Python Pydantic models
    tools/
      get_facts.ts
      get_indicator.ts
      get_central_bank.ts
      get_rate_differentials.ts

Built on:

@modelcontextprotocol/sdk — MCP protocol
zod — input schema validation
stdio transport for communication with the MCP client

API endpoints consumed

| Tool | Endpoint | |------|----------| | get_facts | GET /api/v1/facts | | get_indicator_analysis | GET /api/v1/indicators/{code} | | get_central_bank_sentiment | GET /api/v1/central-banks/{code} | | get_rate_differentials | GET /api/v1/central-banks/rate-matrix |

Build and run locally

cd mcp-server
npm install
npm run build      # compile TypeScript → dist/
npm run dev        # run from source with tsx (watch mode)
npm start          # run the compiled dist/ build

Publishing

See docs/operations/mcp-server-publish.md (internal runbook).

License

MIT