exchange-rates-mcp-server

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['base_currency', 'quote_currency', 'amount'], 'properties': {'date': {'type': 'string', 'description': 'ISO 8601 date (YYYY-MM-DD) for a historical rate. Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.'}, 'amount': {'type': 'number', 'description': 'Amount in the base currency to convert. Must be greater than zero.', 'exclusiveMinimum': 0}, 'base_currency': {'type': 'string', 'description': 'ISO 4217 source currency code (e.g. USD). Call fx_list_currencies to get valid codes.'}, 'quote_currency': {'type': 'string', 'description': 'ISO 4217 target currency code (e.g. EUR). The amount will be expressed in this currency. Call fx_list_currencies to get valid codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['base_currency', 'quote_currency', 'base_amount', 'quote_amount', 'rate', 'rate_date', 'date_snapped', 'rate_type', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rate': {'type': 'number', 'description': 'Exchange rate used: units of quote currency per 1 unit of base currency.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_date_format', 'unsupported_currency', 'date_out_of_range', 'upstream_no_data'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Both currencies are supported but the ECB published no rate for this date. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'source': {'type': 'string', 'description': 'Always "ECB via Frankfurter" â\x80\x94 the upstream data provider.'}, 'rate_date': {'type': 'string', 'description': 'Actual date of the rate used for conversion.'}, 'rate_type': {'type': 'string', 'description': 'Always "ECB reference (mid-market)" â\x80\x94 these are reference rates, not tradeable bid/ask.'}, 'base_amount': {'type': 'number', 'description': 'The input amount in the base currency.'}, 'date_snapped': {'type': 'boolean', 'description': 'True when the API returned a different date than requested â\x80\x94 ECB silently snaps weekend/holiday requests to the prior business day.'}, 'quote_amount': {'type': 'number', 'description': 'The converted amount in the quote currency, rounded to 6 decimal places.'}, 'base_currency': {'type': 'string', 'description': 'Source currency code.'}, 'quote_currency': {'type': 'string', 'description': 'Target currency code.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id'], 'properties': {'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['canvas_id', 'tables', 'expires_at']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_not_found'], 'description': 'Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not exist or has been evicted. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'tables': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'kind', 'row_count', 'columns'], 'properties': {'kind': {'type': 'string', 'description': 'Either "table" or "view".'}, 'name': {'type': 'string', 'description': 'Table or view name.'}, 'columns': {'type': 'array', 'items': {'type': 'object', 'required': ['name', 'type', 'nullable'], 'properties': {'name': {'type': 'string', 'description': 'Column name.'}, 'type': {'type': 'string', 'description': 'DuckDB column type (e.g. VARCHAR, DOUBLE, BIGINT).'}, 'nullable': {'type': 'boolean', 'description': 'Whether the column accepts NULL values.'}}, 'description': 'A single column descriptor.', 'additionalProperties': False}, 'description': 'Column schema for this table.'}, 'row_count': {'type': 'number', 'description': 'Number of rows in this table or view.'}}, 'description': 'A single table or view staged on the canvas.', 'additionalProperties': False}, 'description': 'All tables and views currently staged on this canvas.'}, 'canvas_id': {'type': 'string', 'description': 'The canvas ID echoed back â\x80\x94 use this in fx_dataframe_query.'}, 'expires_at': {'type': 'string', 'description': 'ISO 8601 timestamp when this canvas will be evicted.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['canvas_id', 'query'], 'properties': {'query': {'type': 'string', 'description': "Read-only SQL SELECT statement. Reference tables by the names returned by fx_dataframe_describe or the table_name field from fx_get_timeseries. Example: SELECT date, rate FROM fx_usd_eur WHERE date > '2024-01-01' ORDER BY date"}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Canvas ID returned by fx_get_timeseries. Re-run fx_get_timeseries to obtain a fresh canvas_id if this one has expired.'}, 'row_limit': {'type': 'integer', 'default': 150, 'maximum': 10000, 'minimum': 1, 'description': 'Most rows to return (1â\x80\x9310000, default 150). When the query produces more, truncated is true â\x80\x94 page with ORDER BY <column> LIMIT <n> OFFSET <m> in the SQL, or aggregate, rather than raising this toward the maximum.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['rows', 'row_count', 'truncated', 'canvas_id']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rows': {'type': 'array', 'items': {'type': 'object', 'description': 'One result row â\x80\x94 column-name â\x86\x92 value pairs matching the SELECT columns.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {}}, 'description': 'Result rows, at most row_limit (default 150). Each key is a column name from the query.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['canvas_not_found', 'missing_table', 'invalid_query'], 'description': 'Machine-readable failure mode. Declared by this tool: `canvas_not_found`: canvas_id does not exist or has been evicted. `missing_table`: The SQL references a table that is not staged on this canvas, or whose TTL expired. `invalid_query`: SQL is not a SELECT, references unknown columns, or has a syntax error. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'notice': {'type': 'string', 'description': 'Present when truncated is true: how many rows came back and the ORDER BY â\x80¦ LIMIT â\x80¦ OFFSET query shape that fetches the next page.'}, 'canvas_id': {'type': 'string', 'description': 'The canvas ID used â\x80\x94 pass to a subsequent fx_dataframe_query or fx_dataframe_describe call.'}, 'row_count': {'type': 'number', 'description': 'Rows returned â\x80\x94 always the length of rows. When truncated is true this equals row_limit, not the full result size.'}, 'truncated': {'type': 'boolean', 'description': 'True when the query produced more rows than row_limit and rows holds only the first row_limit of them. Fetch the rest with ORDER BY <column> LIMIT <n> OFFSET <m> â\x80\x94 ORDER BY is required for deterministic paging â\x80\x94 or aggregate to shrink the result.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['base_currency', 'quote_currency'], 'properties': {'date': {'type': 'string', 'description': 'ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.'}, 'base_currency': {'type': 'string', 'description': 'ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes.'}, 'quote_currency': {'type': 'string', 'description': 'ISO 4217 quote currency code (e.g. EUR). The rate is expressed as "how many quote units per 1 base unit". Call fx_list_currencies to get valid codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['base_currency', 'quote_currency', 'rate', 'rate_date', 'date_snapped', 'rate_type', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'rate': {'type': 'number', 'description': 'Exchange rate: units of quote currency per 1 unit of base currency.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_date_format', 'unsupported_currency', 'date_out_of_range', 'upstream_no_data'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Both currencies are supported but the ECB published no rate for this date. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'source': {'type': 'string', 'description': 'Always "ECB via Frankfurter" â\x80\x94 the upstream data provider.'}, 'rate_date': {'type': 'string', 'description': 'Actual date of the rate returned.'}, 'rate_type': {'type': 'string', 'description': 'Always "ECB reference (mid-market)" â\x80\x94 these are reference rates, not tradeable bid/ask.'}, 'date_snapped': {'type': 'boolean', 'description': 'True when the API returned a different date than requested â\x80\x94 ECB silently snaps weekend/holiday requests to the prior business day.'}, 'base_currency': {'type': 'string', 'description': 'The base currency code.'}, 'quote_currency': {'type': 'string', 'description': 'The quote currency code.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['base_currency'], 'properties': {'date': {'type': 'string', 'description': 'ISO 8601 date (YYYY-MM-DD). Omit for the latest available rate. ECB data starts 1999-01-04. Future dates are not supported.'}, 'symbols': {'type': 'array', 'items': {'type': 'string', 'description': 'ISO 4217 currency code to include in the response.'}, 'minItems': 1, 'description': 'Optional list of quote currency codes to filter the response. When provided, must contain at least one currency code â\x80\x94 omit the field entirely, not an empty array, to return all ~30 supported currencies (the base is not among them). Including base_currency here is valid â\x80\x94 it comes back with a rate of 1.'}, 'base_currency': {'type': 'string', 'description': 'ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['base_currency', 'rate_date', 'rates', 'date_snapped', 'rate_type', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_date_format', 'unsupported_currency', 'date_out_of_range', 'upstream_no_data'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_date_format`: date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or an entry in symbols is not in the ECB currency set. `date_out_of_range`: date is before 1999-01-04 or in the future. `upstream_no_data`: Every requested currency is supported but the ECB published no rates for this date. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'rates': {'type': 'object', 'description': 'Map of quote currency code â\x86\x92 exchange rate (units of quote per 1 base).', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'number'}}, 'source': {'type': 'string', 'description': 'Always "ECB via Frankfurter" â\x80\x94 the upstream data provider.'}, 'rate_date': {'type': 'string', 'description': 'Actual date of the rates. May differ from requested date on weekends/holidays â\x80\x94 ECB publishes business days only; the API silently snaps to the prior business day.'}, 'rate_type': {'type': 'string', 'description': 'Always "ECB reference (mid-market)" â\x80\x94 these are reference rates, not tradeable bid/ask.'}, 'date_snapped': {'type': 'boolean', 'description': 'True when the API returned a different date than requested â\x80\x94 ECB silently snaps weekend/holiday requests to the prior business day. Always false when date is omitted.'}, 'base_currency': {'type': 'string', 'description': 'The base currency code.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'required': ['base_currency', 'quote_currency', 'start_date', 'end_date'], 'properties': {'end_date': {'type': 'string', 'description': 'ISO 8601 end date (YYYY-MM-DD). Must be >= start_date. Future dates are not supported.'}, 'canvas_id': {'type': 'string', 'pattern': '^[A-Za-z0-9_-]{10}$', 'description': 'Optional canvas ID from a prior call. Omit on the first call to start a fresh canvas; pass the returned canvas_id to append tables to an existing canvas.'}, 'start_date': {'type': 'string', 'description': 'ISO 8601 start date (YYYY-MM-DD). ECB data starts 1999-01-04. The actual first data point may be later if start_date falls on a weekend/holiday.'}, 'base_currency': {'type': 'string', 'description': 'ISO 4217 base currency code (e.g. USD). Call fx_list_currencies to get valid codes.'}, 'quote_currency': {'type': 'string', 'description': 'ISO 4217 quote currency code (e.g. EUR). Call fx_list_currencies to get valid codes.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['base_currency', 'quote_currency', 'start_date', 'end_date', 'rates', 'rate_count', 'truncated', 'rate_type', 'source', 'spilled']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'examples': ['invalid_date_format', 'unsupported_currency', 'date_out_of_range', 'invalid_range', 'upstream_no_data'], 'description': 'Machine-readable failure mode. Declared by this tool: `invalid_date_format`: start_date or end_date is not a real calendar date written as YYYY-MM-DD. `unsupported_currency`: base_currency or quote_currency is not in the ECB currency set. `date_out_of_range`: start_date is before 1999-01-04 or end_date is in the future. `invalid_range`: start_date is after end_date. `upstream_no_data`: Both currencies are supported but the ECB published no rates across this range. Other values are possible when a failure originates below the handler.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'rates': {'type': 'object', 'description': 'Date â\x86\x92 rate map in date order, publication days inside the requested range only. Holds every publication day when truncated is false; otherwise the first 500 of an inline page (continue with next_start_date) or the preview of a spilled series (the full series is on the canvas). Empty when the range contains no publication day at all.', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'number'}}, 'notice': {'type': 'string', 'description': 'Explains a result that would otherwise look broken or incomplete: an empty series (no publication day in the range); an inline page cut short (the start_date to continue from, plus why a long range was not staged when DataCanvas is not configured); or a spilled series (the canvas and table it was staged to, and the tools that read it).'}, 'source': {'type': 'string', 'description': 'Always "ECB via Frankfurter" â\x80\x94 the upstream data provider.'}, 'spilled': {'type': 'boolean', 'description': 'True when the full result was staged on the DataCanvas (range exceeded threshold).'}, 'end_date': {'type': 'string', 'description': 'Last publication date in the requested range. Always inside the requested range â\x80\x94 earlier than the requested end when that day had no ECB fix, and equal to it when the series is empty. Later than the last key in rates when truncated is true.'}, 'canvas_id': {'type': 'string', 'description': 'Canvas ID â\x80\x94 present when spilled is true. Pass to fx_dataframe_describe to inspect the staged table, then to fx_dataframe_query to run SQL.'}, 'rate_type': {'type': 'string', 'description': 'Always "ECB reference (mid-market)" â\x80\x94 these are reference rates, not tradeable bid/ask.'}, 'truncated': {'type': 'boolean', 'description': 'True when rates holds only part of the series: an inline page (next_start_date continues it) or a spilled preview (spilled is true). False when rates holds every publication day in the requested range.'}, 'rate_count': {'type': 'number', 'description': 'Total publication days in the requested range (the start_date through end_date passed on this call) â\x80\x94 not the number of entries in rates, which is smaller when truncated is true. On a continuation call it counts the days from that start_date onward.'}, 'start_date': {'type': 'string', 'description': 'First publication date in the requested range, and the first key in rates. Always inside the requested range â\x80\x94 later than the requested start when that day had no ECB fix, and equal to it when the series is empty.'}, 'table_name': {'type': 'string', 'description': 'Canvas table name â\x80\x94 present when spilled is true. Use it as the FROM target in fx_dataframe_query SQL; fx_dataframe_describe lists its columns.'}, 'base_currency': {'type': 'string', 'description': 'Base currency code.'}, 'quote_currency': {'type': 'string', 'description': 'Quote currency code.'}, 'next_start_date': {'type': 'string', 'description': 'Present only when an inline page was cut short: the first publication date not in rates. Pass it as start_date with the same end_date to get the next page. Absent on the final page.'}}, 'additionalProperties': False}

{'type': 'object', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'not': {'required': ['error']}, 'required': ['currencies', 'count', 'source']}, {'required': ['error']}], '$schema': 'https://json-schema.org/draft/2020-12/schema', 'properties': {'count': {'type': 'number', 'description': 'Total number of supported currencies.'}, 'error': {'type': 'object', 'required': ['code', 'message'], 'properties': {'code': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991, 'description': 'JSON-RPC error code for this failure.'}, 'data': {'type': 'object', 'properties': {'reason': {'type': 'string', 'description': 'Machine-readable failure mode.'}, 'recovery': {'type': 'object', 'required': ['hint'], 'properties': {'hint': {'type': 'string'}}, 'description': 'Actionable next step for the caller.', 'additionalProperties': {}}, 'retryable': {'type': 'boolean', 'description': 'Whether retrying may succeed.'}}, 'additionalProperties': {}}, 'message': {'type': 'string', 'description': 'Human-readable description of what went wrong.'}}, 'description': 'Present when the call failed. Absent on success.', 'additionalProperties': {}}, 'source': {'type': 'string', 'description': 'Always "ECB via Frankfurter" â\x80\x94 the upstream data provider.'}, 'currencies': {'type': 'array', 'items': {'type': 'object', 'required': ['code', 'name'], 'properties': {'code': {'type': 'string', 'description': 'ISO 4217 currency code (e.g. USD, EUR, JPY).'}, 'name': {'type': 'string', 'description': 'Full currency name (e.g. "United States Dollar").'}}, 'description': 'A single supported currency.', 'additionalProperties': False}, 'description': 'All supported currencies, sorted alphabetically by code.'}}, 'additionalProperties': False}