MCP Server Documentation
With the FundaFX MCP server, LLM agents such as Claude and GPT can search and retrieve economic facts using natural language.
Use it as input data for bot trading, research automation, or portfolio analysis.
Quick start (Claude Desktop / Claude Code)
The fastest way to start using the MCP server from an MCP client. Takes about 3 minutes.
Prerequisites
Have an MCP client ready in advance.
- Claude Desktop: Download and install from https://claude.ai/download
- Claude Code (CLI): Available from any terminal where it has been installed via, e.g.,
npm install -g @anthropic-ai/claude-code - Cursor / Windsurf, etc.: Use a version that supports MCP
Install the FundaFX mobile app and obtain your API key (required)
FundaFX API keys are issued and managed only through the mobile app. Both the Free tier (100 req / month) and the Pro subscription (5,000 req / month) are provided through the app.
- iOS: Download from the App Store
- Android: Google Play release in progress
After launching the app, open Settings > API Key Management and copy the key starting with fndx_.
Register with your MCP client
See the "Setup" section below. For Claude Desktop, paste the JSON into the configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json). For Claude Code, you can register with a single claude mcp add CLI command. Replace fndx_your_api_key_here with the key you obtained.
Restart your client and start asking questions
Claude Desktop activates after a restart; Claude Code activates in a new session. "What is the Fed's policy rate?" "Get the high-importance USD-related facts" — just ask in natural language and the agent will call the right tools automatically.
Setup
Add the following entry to your MCP client's configuration file.
Claude Desktop (JSON config)
Configuration file location:
· macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
· Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"fundafx": {
"command": "npx",
"args": ["fundafx-mcp-server"],
"env": {
"FUNDAFX_API_KEY": "fndx_your_api_key_here",
"FUNDAFX_API_URL": "https://api.fundafx.link"
}
}
}
}
Claude Code (CLI command)
Claude Code provides a dedicated claude mcp add command, so you don't need to write JSON by hand. Adding --scope user makes it available across all projects (omit it for project-scoped registration).
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. You're good when the status shows ✓ Connected.
Cursor / Windsurf and other clients
Cursor, Windsurf, and other MCP-compatible clients can use the same JSON shown above for "Claude Desktop (JSON config)". Paste it into each client's MCP configuration field.
Python MCP server (local)
{
"mcpServers": {
"fundafx": {
"command": "uv",
"args": ["run", "python", "-m", "fundafx.mcp.run"],
"env": {
"DATABASE_URL": "postgresql+asyncpg://..."
}
}
}
}
Environment variables
| Variable | Description | Default |
|---|---|---|
| FUNDAFX_API_KEY | API key (required by the TypeScript version) | — |
| FUNDAFX_API_URL | API base URL | http://localhost:8000 |
| DATABASE_URL | PostgreSQL connection string (required by the Python version) | — |
Available tools
The MCP server provides 4 tools. The LLM picks the right tool automatically based on the context, so you only need to ask questions in natural language.
If you want to retrieve historical (time-series) data, use the include_history=true option of get_indicator_analysis instead of a separate tool.
Search FX fundamental facts. Retrieve economic events, monetary policy decisions, data releases, and market-related news with filters. Returns the most recent items first by event timestamp.
Parameters
| Name | Type | Description |
|---|---|---|
| currency | string optional | Currency code: USD, EUR, JPY, GBP, AUD, CAD, CHF, NZD, CNY |
| fact_type | string optional | institutional_release, official_speech, media_report |
| importance | string optional | high, medium, low |
| source_collector | string optional | Source collector: cb_rss, ecb, gdelt, news_rss, etc. |
| limit | int optional | Number of items to retrieve (1-100, default 20) |
"Get the 5 latest high-importance facts." "Show me EUR-related monetary policy news." "Check this week's USD-related data releases." "Tell me about the geopolitical news collected from GDELT." "Summarize yesterday's JPY-related news."
Get a detailed analysis of a specific economic indicator. Includes the latest value and metadata (unit, frequency, category), and optionally historical data.
Parameters
| Name | Type | Description |
|---|---|---|
| indicator | string required | Indicator code: US_CPI, US_NFP, US_UNEMPLOYMENT, JP_GDP, EU_HICP, GB_CPI, etc. |
| include_history | boolean optional | Include historical data points (default false) |
Indicator codes follow the format <COUNTRY>_<INDICATOR> (ISO 2-letter country code + indicator name). Example: US CPI = US_CPI, Japan GDP = JP_GDP. If a non-existent code is specified, the error response includes a list of available codes.
"Show me the trend of the US CPI for the last 12 months." "Get the time-series data of Japan's GDP growth rate." "Tell me the latest US Non-Farm Payrolls (NFP) data."
Retrieve the current policy rate, next meeting date, and governor information for a central bank. Useful for understanding the current monetary policy stance.
Parameters
| Name | Type | Description |
|---|---|---|
| bank | string required | Central bank code: FED, ECB, BOJ, BOE, RBA, BOC, SNB, RBNZ, PBOC |
"Tell me the Fed's current policy rate and next meeting date." "Who is the ECB president?" "What is the BOJ's policy rate?"
Retrieve interest rate differentials between currency pairs. Shows central bank policy rates and the spread between them — useful for carry-trade analysis.
Parameters
| Name | Type | Description |
|---|---|---|
| base | string optional | Base currency code: USD, EUR, JPY, GBP, AUD, CAD, CHF, NZD, CNY (omit for all currencies) |
| quote | string optional | Quote currency code (same list as above; omit for all currencies) |
"What is the rate differential between USD and JPY?" "Analyze the best currency pairs for carry trades." "Show me the rate differentials across all central banks."
Use cases
Representative use cases for the FundaFX MCP server.
Bot trading
Feed real-time fact data and calendar events to bots that adjust positions around economic data releases.
Research automation
Just ask the LLM agent "Summarize this week's EUR-related news" and get a fact-based report generated automatically.
Portfolio analysis
Combine the rate-differential matrix and economic indicator trends to delegate currency allocation optimization to the AI.
Alerting system
Implement automated calendar-event monitoring and notification triggers on important fact arrivals via the agent.
Market briefings
Auto-generate the morning market summary. The agent summarizes the previous day's important events and today's schedule from structured data.
Backtest support
Retrieve historical economic indicator values and fact data, providing the fundamental data needed to backtest your trading strategy.
Conversation example
An example conversation using FundaFX MCP from Claude Desktop.
User: Tell me the Fed's current policy rate and the rate differentials for major currency pairs. Claude (MCP tool calls): get_central_bank_sentiment(bank="FED") get_rate_differentials(base="USD") Claude: Federal Reserve (Fed) status: - Current policy rate: 4.50% - Chair: Jerome Powell - Next FOMC: 2026-03-18 USD-based major pair rate differentials: USD/JPY: +4.00% (4.50% - 0.50%) USD/EUR: +1.35% (4.50% - 3.15%) USD/GBP: +0.00% (4.50% - 4.50%) USD/AUD: +0.40% (4.50% - 4.10%) USD/CAD: +1.25% (4.50% - 3.25%) USD/CHF: +4.00% (4.50% - 0.50%)
Data sources
Data retrieved through MCP is collected from the 12 sources below.
| Source | Type | Data |
|---|---|---|
| ECB | API | Policy rate, FX rates, macro statistics |
| FRB | RSS | FOMC statements, speeches, press releases |
| e-Stat | API | Japan economic statistics (CPI, GDP, etc.) |
| OECD | API | Macro economic indicators across major countries |
| World Bank | API | Country GDP, population, development indicators |
| EIA | API | Crude oil and energy statistics |
| CFTC | API | Speculator positions (COT report) |
| GDELT | API | Global news events |
| CB RSS | RSS | Official announcements from central banks |
| News RSS | RSS | Major financial news |
| X (Twitter) | API | Posts from key officials and public bodies |
| Treasury Yields | API | U.S. Treasury yields |
FAQ
What is the difference between MCP and the REST API?
The REST API is a traditional interface that retrieves data directly via HTTP requests. MCP is a protocol that lets an LLM agent automatically pick and call the appropriate tool from natural-language context. Internally, the MCP server calls the REST API.
How are rate limits applied?
Requests through the MCP server are subject to the same rate limits as the REST API: 100 / month on the Free tier and 5,000 / month on the Pro tier. Counters reset each month.
What is the difference between the TypeScript and Python versions?
The TypeScript version (npx fundafx-mcp-server) is a remote client that operates via the REST API. The Python version connects to the database directly and is intended for self-hosted environments. We recommend the TypeScript version for general users.
Which clients are supported?
Any client that supports the MCP protocol can use it. We've tested Claude Desktop, Claude Code, Cursor, and Windsurf. Claude Desktop registers via JSON config; Claude Code via the claude mcp add command (see the "Setup" section).
Is the FundaFX mobile app required?
Yes. API key issuance, reissuance, revocation, and Pro plan subscription are all handled in the mobile app. To use the MCP server, install the app first and obtain a key (iOS: App Store; Android: Google Play release in progress).