mcp-banka/README.md

Model Context Protocol Server for Turkish Currency and Exchange Rate data from the Central Bank of The Republic of Turkey (TCMB) (TCMB)

# MCP-Banka

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/mcp-banka.svg)](https://www.npmjs.com/package/mcp-banka)

MCP-Banka is a Model Context Protocol server that provides access to Turkish Currency and Exchange Rate data from the Central Bank of The Republic of Turkey (TCMB).

## Features

- Get today's exchange rates in Turkish Lira (TRY)
- Get historical exchange rates by specific date
- Get a list of all available currencies with their rates
- Get URLs to Central Bank of Turkey's raw exchange rate data

## Installation

```bash
# Using npm
npm install mcp-banka

# Using yarn
yarn add mcp-banka

# Using pnpm
pnpm add mcp-banka
```

## Usage

### Standalone Usage

You can run MCP-Banka directly:

```bash
npx mcp-banka
```

### Integration with MCP Clients

MCP-Banka can be integrated with any Model Context Protocol client like Claude Desktop or other AI applications:

```json
{
  "mcpServers": {
    "banka": {
      "command": "npx",
      "args": ["-y", "mcp-banka"]
    }
  }
}
```

## Available Tools

### 1. Today's Exchange Rate

Gets the current exchange rate for a specified currency against Turkish Lira (TRY).

```typescript
todayExchangeRate({
  currencyCode: string // Optional. Currency code like USD, EUR, GBP
})
```

### 2. Exchange Rate History

Gets the historical exchange rate for a specific date and currency.

```typescript
exchangeRateHistory({
  currencyCode: string, // Required. Currency code like USD, EUR, GBP
  date: string          // Required. Date in YYYY-MM-DD format
})
```

### 3. Get All Currencies

Gets all available currencies and their exchange rates for a specific date.

```typescript
getAllCurrencies({
  date: string // Optional. Date in YYYY-MM-DD format, defaults to today
})
```

### 4. Get Exchange Rate URL

Gets the URL to the raw TCMB exchange rate data for a specific date.

```typescript
getExchangeRateUrl({
  date: string // Optional. Date in YYYY-MM-DD format, defaults to today
})
```

## Development

```bash
# Clone the repository
git clone https://github.com/kiliczsh/mcp-banka.git

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm run test

# Run the MCP inspector for debugging
npm run inspector
```

## Docker Support

You can also run MCP-Banka as a Docker container:

```bash
# Build the Docker image
docker build -t mcp-banka .

# Run the Docker container
docker run -it mcp-banka
```

## Contributing

Contributions are welcome! Please check out our [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests, report issues, or request features.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

- [kiliczsh (Muhammed Kılıç)](https://github.com/kiliczsh)

## Links

- [GitHub Repository](https://github.com/kiliczsh/mcp-banka)
- [Issue Tracker](https://github.com/kiliczsh/mcp-banka/issues)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)