Metadata-Version: 2.4
Name: cbrt-mcp
Version: 0.2.0
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`.

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

Then restart Codex, or 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"]

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

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

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

## Workflow

Use discovery tools before fetching data:

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

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