cbrt-mcp 0.2.2

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.

Update

uvx runs packages from its cache and refreshes them as needed. To force the latest published cbrt-mcp package on the next launch:

uvx --refresh-package cbrt-mcp cbrt-mcp

Then restart your MCP client.

If you want to re-register after changing an EVDS token, run the same install command again for your client. For Codex:

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

For Claude Code:

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

For Claude Desktop, update EVDS_TOKEN in claude_desktop_config.json and restart Claude Desktop.

Metadata Snapshot

The package ships with a bundled CBRT EVDS metadata snapshot. That bundled file lives inside the installed package cache, so users should not edit it directly.

When users refresh metadata, cbrt-mcp writes a separate user snapshot on their machine. The MCP server automatically prefers that user snapshot when it exists and falls back to the bundled snapshot otherwise. No repository clone, package reinstall, or MCP config edit is needed.

Refresh metadata with a temporary EVDS token:

EVDS_TOKEN=paste-your-token-here uvx cbrt-mcp update-metadata

Or pass the token as an option:

uvx cbrt-mcp update-metadata --token paste-your-token-here

Check which snapshot is active:

uvx cbrt-mcp metadata-status

After refreshing metadata, restart the MCP client so any already-running server process reloads the snapshot.

User snapshots are stored outside the installed package:

OS	User snapshot path
macOS	~/Library/Application Support/cbrt-mcp/cbrt_meta_data.csv.gz
Linux	~/.local/share/cbrt-mcp/cbrt_meta_data.csv.gz
Windows	%APPDATA%\cbrt-mcp\cbrt_meta_data.csv.gz

Advanced users can point the server at a custom gzipped metadata CSV with CBRT_MCP_METADATA_PATH.

To go back to the bundled snapshot:

uvx cbrt-mcp reset-metadata

Then restart the MCP client.

Uninstall

Codex:

codex mcp remove cbrt
codex mcp list

Claude Code user-wide install:

claude mcp remove cbrt -s user
claude mcp list

If you installed Claude Code without -s user, run this from the project where you added it:

claude mcp remove cbrt

Claude Desktop: remove the "cbrt" entry from mcpServers in claude_desktop_config.json, then restart Claude Desktop.

Optional cache cleanup:

uv cache clean cbrt-mcp

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