mcp-server-fxmacrodata 0.1.0__py3-none-any.whl

mcp_server_fxmacrodata/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for the FXMacroData API."""
+
+from .server import main
+
+__all__ = ["main"]

mcp_server_fxmacrodata/server.py

@@ -0,0 +1,264 @@
+"""FXMacroData MCP Server — stdio transport for AI agent clients.
+
+Exposes the full FXMacroData API surface as typed MCP tools that any
+MCP-compatible client (Claude Desktop, Cursor, Windsurf, OpenClaw, etc.)
+can discover and invoke.
+
+Usage:
+    uvx mcp-server-fxmacrodata                     # USD data (free)
+    FXMACRODATA_API_KEY=key uvx mcp-server-fxmacrodata   # all currencies
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Optional
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from fxmacrodata import Client, FXMacroDataError
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+API_KEY = os.environ.get("FXMACRODATA_API_KEY", "")
+BASE_URL = os.environ.get("FXMACRODATA_BASE_URL", "https://fxmacrodata.com/api")
+
+_client = Client(api_key=API_KEY or None)
+
+# Override base URL if the user changed it (e.g., for dev server).
+if BASE_URL != "https://fxmacrodata.com/api":
+    _client.BASE_URL = BASE_URL
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    name="FXMacroData",
+    instructions=(
+        "FXMacroData provides macroeconomic indicator data, release calendars, "
+        "COT positioning, commodities, forex rates, and FX market session info. "
+        "USD data is free. Non-USD data requires an API key."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _api_url(path: str) -> str:
+    """Build a full API URL from a relative path."""
+    return f"{BASE_URL}{path}"
+
+
+def _auth_headers() -> dict[str, str]:
+    """Return auth headers if an API key is configured."""
+    if API_KEY:
+        return {"X-API-Key": API_KEY}
+    return {}
+
+
+def _handle_error(tool_name: str, exc: Exception) -> str:
+    """Format a tool error as a user-friendly JSON string."""
+    msg = str(exc)
+    if "API key required" in msg or "401" in msg:
+        return json.dumps({
+            "error": f"{tool_name} requires an API key for this request.",
+            "help": "Set the FXMACRODATA_API_KEY environment variable. "
+                    "Get your key at https://fxmacrodata.com/api-management",
+        })
+    return json.dumps({"error": msg})
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool(
+    name="ping",
+    description="Verify that the FXMacroData API is reachable.",
+)
+def ping() -> str:
+    """Health check."""
+    resp = httpx.get(_api_url("/v1/ping"), headers=_auth_headers(), timeout=10)
+    resp.raise_for_status()
+    return json.dumps(resp.json())
+
+
+@mcp.tool(
+    name="data_catalogue",
+    description=(
+        "List available macroeconomic indicators for a currency. "
+        "Supported currencies include: AUD, BRL, CAD, CHF, CNY, DKK, EUR, "
+        "GBP, JPY, NZD, PLN, SEK, SGD, USD."
+    ),
+)
+def data_catalogue(currency: str) -> str:
+    """Return the indicator catalogue for a currency."""
+    try:
+        result = _client.get_data_catalogue(currency)
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("data_catalogue", exc)
+
+
+@mcp.tool(
+    name="release_calendar",
+    description=(
+        "Get upcoming macroeconomic release dates for a currency, with optional "
+        "indicator filter."
+    ),
+)
+def release_calendar(currency: str, indicator: Optional[str] = None) -> str:
+    """Return the release calendar for a currency."""
+    try:
+        result = _client.get_calendar(currency, indicator=indicator)
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("release_calendar", exc)
+
+
+@mcp.tool(
+    name="forex",
+    description=(
+        "Get FX spot rates for a currency pair with optional technical indicators. "
+        "The indicators parameter accepts a comma-separated list of technical "
+        "indicator slugs (e.g. 'sma_20,ema_50,rsi_14,bbands_20,atr_14,macd')."
+    ),
+)
+def forex(
+    base: str,
+    quote: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    indicators: Optional[str] = None,
+) -> str:
+    """Return FX spot rates and optional technical indicators."""
+    try:
+        result = _client.get_fx_price(
+            base, quote,
+            start_date=start_date,
+            end_date=end_date,
+            indicators=indicators,
+        )
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("forex", exc)
+
+
+@mcp.tool(
+    name="indicator_query",
+    description=(
+        "Get macroeconomic indicator time series for a currency. "
+        "Returns announcement dates, values, and prior readings. "
+        "Use data_catalogue to discover valid currency + indicator slugs."
+    ),
+)
+def indicator_query(
+    currency: str,
+    indicator: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+) -> str:
+    """Return an indicator announcement time series."""
+    try:
+        # Match the hosted MCP behaviour: COMM routes to commodities
+        if currency.upper() == "COMM":
+            result = _client.get_commodities(
+                indicator, start_date=start_date, end_date=end_date,
+            )
+        else:
+            result = _client.get_indicator(
+                currency, indicator,
+                start_date=start_date, end_date=end_date,
+            )
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("indicator_query", exc)
+
+
+@mcp.tool(
+    name="market_sessions",
+    description=(
+        "Get the current FX market-session timetable and overlap windows, "
+        "or request a snapshot for a specific UTC timestamp. "
+        "Covers Sydney, Tokyo, London, and New York sessions."
+    ),
+)
+def market_sessions(at: Optional[str] = None) -> str:
+    """Return FX market session status."""
+    params: dict[str, str] = {}
+    if at:
+        params["at"] = at
+    resp = httpx.get(
+        _api_url("/v1/market_sessions"),
+        params=params,
+        headers=_auth_headers(),
+        timeout=10,
+    )
+    resp.raise_for_status()
+    return json.dumps(resp.json())
+
+
+@mcp.tool(
+    name="cot_data",
+    description=(
+        "Get CFTC Commitment of Traders (COT) weekly positioning data "
+        "for a currency's FX futures contract. "
+        "Supported: AUD, CAD, CHF, EUR, GBP, JPY, NZD, USD."
+    ),
+)
+def cot_data(
+    currency: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+) -> str:
+    """Return COT positioning data for a currency."""
+    try:
+        result = _client.get_cot(
+            currency, start_date=start_date, end_date=end_date,
+        )
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("cot_data", exc)
+
+
+@mcp.tool(
+    name="commodities",
+    description=(
+        "Get commodity price time series. "
+        "Supported indicators: gold, silver, platinum."
+    ),
+)
+def commodities(
+    indicator: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+) -> str:
+    """Return commodity price data."""
+    try:
+        result = _client.get_commodities(
+            indicator, start_date=start_date, end_date=end_date,
+        )
+        return json.dumps(result)
+    except FXMacroDataError as exc:
+        return _handle_error("commodities", exc)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    """Run the MCP server on stdio transport."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_server_fxmacrodata-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: mcp-server-fxmacrodata
+Version: 0.1.0
+Summary: MCP server for the FXMacroData API — macroeconomic indicators, release calendars, COT, commodities, and forex for AI agents.
+Author-email: FXMacroData <info@fxmacrodata.com>
+License: MIT
+Project-URL: Homepage, https://fxmacrodata.com
+Project-URL: Documentation, https://fxmacrodata.com/documentation
+Project-URL: Source, https://github.com/fxmacrodata/mcp-server-fxmacrodata
+Project-URL: Issues, https://github.com/fxmacrodata/mcp-server-fxmacrodata/issues
+Keywords: mcp,model-context-protocol,forex,macro,macroeconomics,trading,fxmacrodata,ai-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: fxmacrodata>=1.1
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: python-dotenv>=1.1; extra == "dev"
+Requires-Dist: ruff>=0.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# mcp-server-fxmacrodata
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [FXMacroData API](https://fxmacrodata.com) — macroeconomic indicators, release calendars, COT positioning, commodities, and FX rates for AI agents.
+
+## Quick start
+
+No install needed — run with [`uvx`](https://docs.astral.sh/uv/guides/tools/):
+
+```bash
+uvx mcp-server-fxmacrodata
+```
+
+USD data works immediately with no API key. For all currencies, set your key:
+
+```bash
+FXMACRODATA_API_KEY=your_key uvx mcp-server-fxmacrodata
+```
+
+Get a free API key at [fxmacrodata.com/api-management](https://fxmacrodata.com/api-management).
+
+## Configure your MCP client
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fxmacrodata": {
+      "command": "uvx",
+      "args": ["mcp-server-fxmacrodata"],
+      "env": {
+        "FXMACRODATA_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "fxmacrodata": {
+      "command": "uvx",
+      "args": ["mcp-server-fxmacrodata"],
+      "env": {
+        "FXMACRODATA_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "fxmacrodata": {
+      "command": "uvx",
+      "args": ["mcp-server-fxmacrodata"],
+      "env": {
+        "FXMACRODATA_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "mcpServers": {
+    "fxmacrodata": {
+      "command": "uvx",
+      "args": ["mcp-server-fxmacrodata"],
+      "env": {
+        "FXMACRODATA_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+> **Tip:** If your MCP client supports remote HTTP servers, you can connect directly to `https://fxmacrodata.com/mcp` instead — no local install needed. Append `?api_key=your_key` for non-USD data.
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `ping` | Verify FXMacroData API connectivity |
+| `data_catalogue` | List available indicators for a currency |
+| `release_calendar` | Upcoming macro release dates |
+| `forex` | FX spot rates with optional technical indicators |
+| `indicator_query` | Macro indicator time series (announcements) |
+| `market_sessions` | FX session timetable (Sydney, Tokyo, London, New York) |
+| `cot_data` | CFTC Commitment of Traders positioning |
+| `commodities` | Commodity prices (gold, silver, platinum) |
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FXMACRODATA_API_KEY` | *(none)* | API key for non-USD data |
+| `FXMACRODATA_BASE_URL` | `https://fxmacrodata.com/api` | Override API base URL |
+
+## Install with pip
+
+```bash
+pip install mcp-server-fxmacrodata
+```
+
+Then run:
+
+```bash
+mcp-server-fxmacrodata
+```
+
+## Development
+
+```bash
+git clone https://github.com/fxmacrodata/mcp-server-fxmacrodata
+cd mcp-server-fxmacrodata
+pip install -e ".[dev]"
+pytest
+```
+
+## Debugging
+
+Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector uvx mcp-server-fxmacrodata
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_server_fxmacrodata-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mcp_server_fxmacrodata/__init__.py,sha256=JSTyR1k-ocdxjbpcTurKDwfpCq3xiUsOdwGp1DtDsIU,93
+mcp_server_fxmacrodata/server.py,sha256=Ztp06GI7_M0iGfMyxuHBtdPszH241S_yrApYwDi2Kc0,8268
+mcp_server_fxmacrodata-0.1.0.dist-info/licenses/LICENSE,sha256=mLVV_vNUMbtObjBLP4s10Tc8K4m_5sbNJ96E169Td84,1089
+mcp_server_fxmacrodata-0.1.0.dist-info/METADATA,sha256=Wag65dWKyitCpsc5gApgBHF9ifefj_uyobykih3MdmU,4832
+mcp_server_fxmacrodata-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_server_fxmacrodata-0.1.0.dist-info/entry_points.txt,sha256=2_53kqyMfj4L323faofTwQe65-JHqrYmAXYDwL_Vmys,78
+mcp_server_fxmacrodata-0.1.0.dist-info/top_level.txt,sha256=irHYDi4E5aeN3WrMw-hAL6ursJjPjBPAUl5E3KKIDuw,23
+mcp_server_fxmacrodata-0.1.0.dist-info/RECORD,,

mcp_server_fxmacrodata-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_server_fxmacrodata-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-fxmacrodata = mcp_server_fxmacrodata.server:main

mcp_server_fxmacrodata-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FXMacroData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_fxmacrodata-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server_fxmacrodata