cbrt-mcp 0.2.0

Python stdio MCP server for CBRT EVDS time series data

cbrt-mcp

cbrt-mcp is a stdio MCP server for the CBRT EVDS time series API.

It gives MCP clients offline discovery over a bundled CBRT metadata snapshot and live data retrieval from EVDS when an API token is available.

Install

End users do not need to clone this repository. They need:

• uv available on PATH, which provides uvx
• an MCP client that can run stdio servers
• an EVDS token only if they want live data from get_series_data()

Check that uvx is available:

uvx --version

Codex

The recommended Codex setup is the CLI command below. It installs nothing into the repository; it writes the MCP registration to ~/.codex/config.toml.

codex mcp add cbrt \
  --env EVDS_TOKEN=paste-your-token-here \
  -- uvx cbrt-mcp

Then restart Codex, or check the registration from a terminal:

codex mcp list

If you only want metadata tools, omit the token:

codex mcp add cbrt -- uvx cbrt-mcp

Manual Codex configuration is also possible. Edit ~/.codex/config.toml and add:

[mcp_servers.cbrt]
command = "uvx"
args = ["cbrt-mcp"]

[mcp_servers.cbrt.env]
EVDS_TOKEN = "paste-your-token-here"

For metadata-only usage, remove the [mcp_servers.cbrt.env] section.

Claude Desktop and Claude Code

If your client does not have an MCP add command, edit its MCP config file.

Common config paths:

Client	macOS / Linux	Windows
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	~/.claude.json	%USERPROFILE%\.claude.json

Add this server entry under mcpServers:

{
  "mcpServers": {
    "cbrt": {
      "command": "uvx",
      "args": ["cbrt-mcp"],
      "env": {
        "EVDS_TOKEN": "paste-your-token-here"
      }
    }
  }
}

For metadata-only usage, remove the env block.

After changing a config file, restart the MCP client so it reloads the server configuration.

Use From Source

To run the current GitHub version before a PyPI release:

codex mcp add cbrt \
  --env EVDS_TOKEN=paste-your-token-here \
  -- uvx --from git+https://github.com/emraher/cbrt-mcp cbrt-mcp

To run a local checkout:

codex mcp add cbrt \
  --env EVDS_TOKEN=paste-your-token-here \
  -- uvx --from /absolute/path/to/cbrt-mcp cbrt-mcp

EVDS Token

Most tools work offline from the bundled metadata. Only get_series_data() needs EVDS_TOKEN.

Get a free token from https://evds3.tcmb.gov.tr/ and pass it through your MCP client configuration. Do not commit tokens to the repository.

Tools

Tool	Description	Needs token?
suggest_series(query, limit)	Suggest likely series codes with ranking and match context	No
search_series(query, limit)	Search bundled series metadata by keyword	No
get_common_topic_series(topic)	Return curated starter codes for common macro topics	No
get_cbrt_reference(topic)	Return built-in workflow and reference guidance	No
get_series_brief(series_codes)	Return compact descriptions with source and tag preview	No
get_series_availability(series_codes)	Return frequency and date-range summaries	No
get_series_compare_ready(series_codes)	Check whether multiple series are suitable for direct comparison	No
get_series_metadata(series_codes)	Look up metadata for exact series codes	No
get_series_data(series_codes, start_date, end_date, formulas, preview, summary, max_rows)	Download EVDS observations	Yes

The bundled metadata snapshot contains 31,713 EVDS series. Live data requests are chunked for long date ranges to reduce the risk of truncated EVDS responses.

Example Prompts

Search for series related to usd exchange rate
Suggest the best CBRT series codes for Turkish policy rate data
Show me the built-in guidance for formula codes
Check the availability range for TP.DK.USD.A and TP.DK.EUR.A
Can TP.DK.USD.A and TP.FE.OKTG01 be compared directly?
Preview the first 5 rows of TP.DK.USD.A for 2023
Summarize TP.DK.USD.A coverage for 2023 without returning row data
Give me starter CBRT series for reserves

Workflow

Use discovery tools before fetching data:

get_common_topic_series("fx")
suggest_series("usd exchange rate")
get_series_metadata(["TP.DK.USD.A"])
get_series_data(["TP.DK.USD.A"], "01-01-2023", "31-12-2023")

Use get_series_compare_ready() before comparing two or more exact series. Use summary=True when you need coverage and shape information without row records. Dates must use dd-mm-yyyy format.

Development

uv run --frozen --extra dev pytest
uv build --no-sources
uvx twine check dist/*

The server entry point is:

uv run --frozen cbrt-mcp

See Publishing for the PyPI release workflow.

License

MIT