Metadata-Version: 2.4
Name: cbrt-mcp
Version: 0.2.2
Summary: Python stdio MCP server for CBRT EVDS time series data
Project-URL: Homepage, https://github.com/emraher/cbrt-mcp
Project-URL: Repository, https://github.com/emraher/cbrt-mcp
Project-URL: Issues, https://github.com/emraher/cbrt-mcp/issues
Author-email: Emrah Er <eer@eremrah.com>, Mucahit Zor <mucahit.zor01@gmail.com>
License: MIT
License-File: LICENSE.md
Keywords: cbrt,central-bank,evds,mcp,turkey
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.27
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# cbrt-mcp

`cbrt-mcp` is a stdio MCP server for the
[CBRT EVDS](https://evds3.tcmb.gov.tr/) 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`](https://docs.astral.sh/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:

```bash
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.

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

Check the registration from a terminal:

```bash
codex mcp list
```

If you only want metadata tools, omit the token:

```bash
codex mcp add cbrt -- uvx cbrt-mcp
```

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

```toml
[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.

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

For metadata-only usage:

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

Check the registration with:

```bash
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`:

```json
{
  "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:

```bash
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:

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

For Claude Code:

```bash
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:

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

Or pass the token as an option:

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

Check which snapshot is active:

```bash
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:

```bash
uvx cbrt-mcp reset-metadata
```

Then restart the MCP client.

## Uninstall

Codex:

```bash
codex mcp remove cbrt
codex mcp list
```

Claude Code user-wide install:

```bash
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:

```bash
claude mcp remove cbrt
```

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

Optional cache cleanup:

```bash
uv cache clean cbrt-mcp
```

## Use From Source

To run the current GitHub version before a PyPI release:

```bash
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:

```bash
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

```text
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

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

The server entry point is:

```bash
uv run --frozen cbrt-mcp
```

See [Publishing](docs/PUBLISHING.md) for the PyPI release workflow.

## License

MIT
