Metadata-Version: 2.4
Name: mcp-server-fxmacrodata
Version: 0.1.2
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/?utm_source=pypi&utm_medium=referral&utm_campaign=mcp-server-fxmacrodata&utm_content=homepage
Project-URL: Documentation, https://fxmacrodata.com/documentation?utm_source=pypi&utm_medium=referral&utm_campaign=mcp-server-fxmacrodata&utm_content=docs
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<2,>=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/?utm_source=github&utm_medium=referral&utm_campaign=mcp-server-fxmacrodata&utm_content=readme) — 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
```

Evaluate the MCP server with public USD macroeconomic data without an API key,
covering the most recent 90 days. Connect an FXMacroData subscription for
non-USD data, full available history, FX rates, COT and commodities:

```bash
FXMACRODATA_API_KEY=your_key uvx mcp-server-fxmacrodata
```

[Subscribe to FXMacroData](https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=mcp-server-fxmacrodata&utm_content=subscribe), then connect the server using your own account's API key.

For a provider-agnostic install guide that works across multiple AI clients, see [llms-install.md](llms-install.md).

## 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://api.fxmacrodata.com` | 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).
