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