# Currency Exchange MCP Server

A Model Context Protocol (MCP) server that provides real-time currency exchange rates and conversions for 200+ currencies. Built with FastMCP 2.0, designed for remote deployment, and optimized for use with Claude Desktop and other MCP clients.

### Available Tools

- `get_available_currencies` - Get a list of all supported currencies with their full names.

- `get_exchange_rate` - Get the current exchange rate between two currencies.

  - Required arguments:
    - `from_currency` (required): Source currency code (e.g., 'usd', 'eur')
    - `to_currency` (required): Target currency code (e.g., 'gbp', 'jpy')
    - `date` (optional): Date in YYYY-MM-DD format (defaults to latest)

- `convert_currency` - Convert an amount from one currency to another.

  - Required arguments:
    - `amount` (required): Amount to convert
    - `from_currency` (required): Source currency code
    - `to_currency` (required): Target currency code
    - `date` (optional): Date in YYYY-MM-DD format

- `get_all_rates` - Get all exchange rates for a base currency.

  - Required arguments:
    - `base_currency ` (required): Base currency code
    - `date` (optional): Date in YYYY-MM-DD format

- `compare_rates` - Compare exchange rates between a base currency and multiple target currencies.

  - Required arguments:
    - `base_currency` (required): Base currency code
    - `target_currencies` (required): Comma-separated currency codes
    - `date` (optional): Date in YYYY-MM-DD format

### Source

- https://github.com/fawazahmed0/exchange-api

## Deployment

This project is deployed to Google Cloud Run using GitLab CI/CD.

The deployment job uses source-based deployment:

- `gcloud run deploy ... --source .`

The Cloud Run service name is:

- `currency-exchange-mcp-server`

Default deployment region in the pipeline:

- `europe-west1`

## DevOps Pipeline (GitLab CI/CD)

Pipeline definition files:

- `.gitlab-ci.yml`
- `infra/.gitlab-ci-terraform.yml`

### Stages

1. `test`
2. `terraform`
3. `deploy`

### What Happens in Each Stage

1. Test (`run_test`)
- Runs when Python source or dependency files change.
- Uses `uv` and executes `pytest`.

2. Terraform (`terraform_validate`, `terraform_plan`, `terraform_apply`)
- Initializes Terraform in `infra/`.
- Uses GitLab HTTP backend for remote Terraform state.
- Validates, plans, and applies infrastructure.
- Exports `GITLAB_DEPLOYER_SA_EMAIL` from Terraform output as a dotenv artifact.

3. Deploy (`deploy-to-cloud-run`)
- Depends on `terraform_apply` output.
- Authenticates to GCP using a service account key from CI variables.
- Deploys the current source to Cloud Run.

## Terraform Infrastructure

Terraform files:

- `infra/main.tf`
- `infra/variables.tf`
- `infra/terraform.tfvars`

Current Terraform provisions:

- A GitLab deployer service account.
- IAM roles required for Cloud Run deployment and build operations.
- A proxy service account with Cloud Run invoker permissions.
- Required Google APIs:
  - Cloud Build API
  - Cloud Run API
  - Artifact Registry API
  - Cloud Storage API

### Local Terraform Commands

Run from `infra/`:

```bash
terraform init
terraform validate
terraform plan
terraform apply
```

## Required GitLab CI/CD Variables

Set these variables in GitLab project settings:

- `GCP_PROJECT_ID`: Target Google Cloud project ID.
- `GCP_SERVICE_ACCOUNT_KEY`: Base64-encoded JSON key used by the deploy job.
- `TERRAFORM_SERVICE_ACCOUNT_KEY`: Base64-encoded JSON key used by Terraform jobs.

Variables used internally by the Terraform pipeline include:

- `TF_STATE_ADRESS` (as defined in pipeline file): GitLab Terraform state endpoint.
- `TF_HTTP_USERNAME`: `gitlab-ci-token`.
- `TF_HTTP_PASSWORD`: `$CI_JOB_TOKEN`.

## End-to-End Flow

1. Commit changes on `main` (or open a merge request for test stage evaluation).
2. Tests run when application code or Python dependencies change.
3. Terraform jobs run when files in `infra/` change.
4. Terraform apply publishes the deployer service account email as pipeline artifact.
5. Cloud Run deployment runs when app-related files change and uses the Terraform output service account.

## Notes

- Workload Identity Federation resources are present in `infra/main.tf` but currently commented out.
- Current pipeline uses service account keys from GitLab CI variables.