cbrt-mcp 0.2.1

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 CLI and Codex Desktop use this same config, so restart Codex Desktop after adding the server.

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

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"]
startup_timeout_sec = 120

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

For metadata-only usage, remove the [mcp_servers.cbrt.env] section. uvx can take longer than 30 seconds on the first run while it downloads and caches the package, so startup_timeout_sec = 120 is recommended for Codex.

Claude Code

Claude Code also supports a one-line install. Use -s user for a user-wide registration. This config is for Claude Code only; it does not automatically add the server to Claude Desktop.

claude mcp add -s user \
  -e EVDS_TOKEN=paste-your-token-here \
  cbrt -- uvx cbrt-mcp

For metadata-only usage:

claude mcp add -s user cbrt -- uvx cbrt-mcp

Check the registration with:

claude mcp list

Omit -s user if you want Claude Code to add the server only for the current project.

Claude Desktop

Claude Desktop has its own MCP config file. Installing into Claude Code does not automatically make the server available in Claude Desktop.

Common config paths:

Client	macOS / Linux	Windows
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	%APPDATA%\Claude\claude_desktop_config.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

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