mcp-turkiye

mcp-turkiye

土耳其公共数据，尽在一个 MCP 服务中。 适用于 Claude、Cursor、VS Code、Codex 以及所有支持 MCP 的助手：土耳其共和国中央银行（TCMB）外汇汇率、TCMB EVDS 统计数据（通胀、利率、超过 4 万条序列）、BIST 每日价格、加密货币里拉价格、AFAD 和 Kandilli 地震目录、MGM 天气状况与预警、燃油价格、伊斯坦布尔实时交通指数、值班药房（伊斯坦布尔、伊兹密尔）、İSPARK 停车场占用情况、伊斯坦布尔空气质量、伊斯坦布尔地铁线路／车站／公告、伊兹密尔 ESHOT 实时公交和批发市场价格、伊斯坦布尔／伊兹密尔／科尼亚／加济安泰普开放数据门户、《官方公报》索引与正文、mevzuat.gov.tr 上的法律／法规搜索及逐条更新后的文本、法定节假日、ÖSYM 考试日历、官方参数（最低工资、SGK 缴费基数下限／上限）、81 个省和 973 个县的人口／面积／车牌信息、AA 和 TRT 新闻标题，以及 TCKN／VKN／IBAN 格式验证——每条答复均附带来源和获取时间。

将土耳其公共数据汇集至一个 MCP 服务：中央银行外汇汇率、中央银行 EVDS 统计服务（通胀、利率、超过 40,000 条序列）、Borsa İstanbul 每日价格、里拉计价的加密货币价格、全国和 Kandilli 地震目录、国家气象服务的观测数据、预报和预警、县级燃油价格、伊斯坦布尔实时交通指数、值班药房（伊斯坦布尔、İzmir）、İSPARK 停车场占用情况、伊斯坦布尔空气质量、伊斯坦布尔地铁线路／车站／公告、İzmir 实时公交和食品批发价格、伊斯坦布尔、İzmir、科尼亚和加济安泰普的开放数据门户（搜索、数据集、DataStore 行）、《官方公报》每日索引和文章正文、mevzuat.gov.tr 上的整合版法律法规搜索及逐条文本、法定节假日、全国考试日历、官方年度数据（最低工资、社会保障缴费基数下限／上限）、省和县概况、AA／TRT 新闻标题，以及离线验证身份证号／税号／IBAN 校验和。每条答复均附带来源和获取时间。

这是一个独立项目。 mcp-turkiye 并非任何公共机构的官方服务。MIT 许可证仅涵盖代码；每个数据源均有各自的使用条款（SOURCES.md），且服务器的使用须遵守可接受使用政策。

安装

只需 Node.js 20+；无需安装其他内容。只有使用 TCMB EVDS 工具时才需要密钥（免费，见下文）；其他所有功能均无需密钥。

Claude Code

claude mcp add turkiye -- npx -y mcp-turkiye

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "turkiye": { "command": "npx", "args": ["-y", "mcp-turkiye"] }
  }
}

Cursor / VS Code — .cursor/mcp.json 或 .vscode/mcp.json：

{
  "mcpServers": {
    "turkiye": { "command": "npx", "args": ["-y", "mcp-turkiye"] }
  }
}

Cline — 在 MCP 设置中使用相同的 mcpServers 条目；如需让 Cline 自行完成安装，请参阅分步说明：llms-install.md。

然后用土耳其语向助手提问：

“今天 TCMB 美元卖出汇率是多少，来自哪份公报？” “年度通胀率是多少，政策利率是多少，最近公布的是哪个月的数据？” “过去三天有过 4 级以上的地震吗？” “Kadıköy 天气怎么样，周末会下雨吗？” “今天有气象预警吗，覆盖 Ankara 吗？” “根据 Kandilli，过去 24 小时发生了多少次 3 级以上的地震？” “KPSS 成绩何时公布，ALES/3 何时开始报名？” “Bornova 的柴油多少钱一升？” “İBB 开放数据中有停车场数据吗，展示一下表格。” “今天的《官方公报》发布了哪些条例，概述第一条。” “KVKK 第 6 条规定了什么，什么是特殊类别个人数据？” “2026 年最低工资净额是多少里拉，SGK 上限是多少，依据哪部法律？” “《劳动法》哪一条规定了通知期限，期限是多少周？” “THYAO 过去一个月表现如何，相较于 BIST 100 呢？” “过去 8 个月的年度通胀率走势如何？” (使用 EVDS 密钥) “伊斯坦布尔现在的交通状况如何？” “2026 年 10 月 29 日是星期几，是工作日吗？” “TR33 0006 1005 1978 6457 8413 26 是有效的 IBAN 吗，属于哪家银行？”

远程服务（Docker）

无需在每台机器上安装，可将服务一次性部署到云端，让客户端通过 URL 连接。每个版本都会将镜像发布到 ghcr.io/berkantacun/mcp-turkiye；内置的 Streamable HTTP 入口点（dist/http.js）会在 /mcp 路径提供相同的工具和相同的封装。该服务是无状态的（没有会话 ID），因此也可以部署在多个副本后面运行。

docker run -p 8080:8080 -e MCP_TURKIYE_API_KEY=<gizli-anahtar> ghcr.io/berkantacun/mcp-turkiye
claude mcp add --transport http turkiye http://localhost:8080/mcp --header "X-API-Key: <gizli-anahtar>"

不使用 Docker：npm run build && HOST=127.0.0.1 PORT=8080 node dist/http.js（在本地使用 127.0.0.1，以便仅允许本机访问）。

环境变量	默认值	作用
PORT	8080	监听的端口
HOST	0.0.0.0	监听的地址；在不支持 IPv6 的环境（Azure Container Apps）中，:: 无法使用
MCP_TURKIYE_API_KEY	—	设置后，每个 /mcp 请求都必须包含 X-API-Key 标头，否则返回 401。旧名称 MCP_PROXY_API_KEY 也有效
MCP_TURKIYE_RATE_LIMIT	60	每个 IP 每分钟的请求上限；超出后返回 429 和 Retry-After。设为 0 可关闭
TRUST_PROXY	—	设为 1 时，从 X-Forwarded-For 最右侧的条目读取客户端 IP；仅在可信反向代理后面启用
MCP_TURKIYE_ALLOWED_ORIGINS	—	允许从浏览器调用的来源，使用逗号分隔（* 表示全部）。携带 Origin 标头且来源不在列表中的请求会收到 403；MCP 客户端不会发送此标头，浏览器会发送（包括 DNS rebinding 攻击）

• GET /health 无需密钥即可返回 200，且不计入速率限制；可用于健康检查。
• 请求体超过 1 MB 时会收到 413；收到 SIGTERM 时，服务器会停止接受新连接，并完成正在处理的请求（最长 10 秒）。
• 不要在公开端点上无密钥运行：这会让服务器成为开放代理，代你向公共机构发送请求。
• 速率限制仅保存在内存中，且按副本单独计算；运行多个副本时，总限制会乘以副本数量。
• Konya 开放数据门户会拒绝来自土耳其境外的 IP；如果云服务部署在境外区域，acikveri_* 工具会针对 Konya 返回错误，其他来源仍可正常使用（已在 Azure Container Apps 的 Germany West Central 区域测试）。

连接到 claude.ai / Claude Desktop 作为远程服务

在 Claude Desktop 中，单台机器使用上述本地安装（npx）即可。远程连接器适用于在 claude.ai（网页、移动端）上使用服务器，或避免在每台机器上安装。本项目不运营公开端点；您需要先使用上述镜像自行部署服务器。

前提条件（Anthropic 文档）：

• 服务器必须可通过 HTTPS 从公共互联网访问。连接由 Anthropic 的服务器发起，而不是由您的机器发起；Claude Desktop 也是如此。Anthropic 的出站 IP 范围为 160.79.104.0/21（IP 地址）；请在防火墙中允许此范围。
• 地址格式为 https://<alan-adınız>/mcp；传输方式为 Streamable HTTP。

添加：

• Free、Pro、Max： 选择 Customize → Connectors → Add custom connector，然后输入名称和 URL。
• Team、Enterprise： 组织所有者通过 Organization settings → Connectors → Add → Custom → Web 添加；成员在 Customize → Connectors 中点击 Connect。
• 可在聊天中通过 + → Connectors 菜单启用或禁用连接器。

密钥（MCP_TURKIYE_API_KEY）：

• 如果添加窗口中有 Request headers 部分：在身份验证中选择 No sign-in，然后从列表中选择 x-api-key 作为标头，并直接将密钥填入值。此功能处于 Beta 阶段，且仅对部分组织开放。
• 如果没有此部分，Claude 无法发送 X-API-Key，带密钥的服务器会对每个请求返回 401。关闭密钥会使服务器变成开放代理（请参阅上方警告）。此时请在 Claude Desktop 中使用本地安装。如果您决定不使用密钥，至少应在防火墙中仅允许 160.79.104.0/21；此范围承载所有 Claude 用户的连接器流量，知道 URL 的其他 Claude 用户仍可连接。
• 添加后无法更改身份验证设置。更换密钥时，请删除连接器并重新添加。

须知：

• 来自 Claude 的所有请求都来自 Anthropic 的出站地址，因此按 IP 计算的速率限制由这些地址共享。在有多名用户的组织中，您可能需要提高 MCP_TURKIYE_RATE_LIMIT。如果服务器位于反向代理后，请设置 TRUST_PROXY=1，否则所有请求都会被视为来自代理地址。
• 在 claude.ai 和 Desktop 中，工具调用最长可持续 240 秒，工具结果上限约为 150.000 个字符（技术限制）。
• 仅在您自己的机器上运行（127.0.0.1、localhost）的服务器无法连接到 claude.ai：Anthropic 的服务器无法访问它。Claude Code 则从您的机器发起连接；对于本地服务器，请使用上方的 claude mcp add --transport http 命令。

工具

工具	功能	来源
tcmb_kurlar	当日（或指定日期）的 TCMB 指示汇率公告，涵盖所有货币	TCMB
tcmb_kur	单一货币的汇率——注意 birim 字段，JPY 按 100 单位报价	TCMB
evds_kategoriler	EVDS 主题树（价格、利率、汇率、国际收支、调查、住房……）	TCMB EVDS*
evds_veri_gruplari	某个类别中的数据组：代码、频率、单位、日期范围	TCMB EVDS*
evds_seriler	某个数据组中的序列，可按名称筛选	TCMB EVDS*
evds_seri	一个或多个序列的观测值；公式（同比变化等）、频率和汇总选项	TCMB EVDS*
evds_gosterge	无需知道代码即可按名称查询主要指标：年度/每月通胀、PPI、政策利率、美元/欧元/英镑、房价指数、实际有效汇率；返回最新值和日期	TCMB EVDS*
bist_hisse	一只股票的日终价格历史（收盘价、加权平均价、最低/最高价、成交量、市值）+ 当日 BIST 100 和 USD/TRY	İş Yatırım
btcturk_kripto	加密资产的实时 TL（或 USDT）价格：最新价、买入/卖出价、每日变动、成交量；可指定代币列表或按成交量取前 30 名	BtcTurk
afad_depremler	按日期范围、最低震级和数量限制获取地震列表；按时间从新到旧排列	AFAD
kandilli_depremler	Kandilli 天文台的近期地震——独立于 AFAD 的第二套目录；ML/Mw/MD，初步/修订数据	Kandilli
mgm_hava_durumu	查询省/县的实时观测（温度、体感温度、湿度、风、气压、天气现象）+ 5 天预报	MGM
mgm_uyarilar	当前有效的气象预警（强降雨、风暴、降雪……），含完整文本；可按 il 筛选	MGM
opet_akaryakit	按县查询汽油/柴油/煤油/燃料油泵价；包括伊斯坦布尔的欧亚两岸	Opet
ibb_trafik_indeksi	伊斯坦布尔全市实时交通拥堵指数（0–100），每次调用均获取最新数据	İBB
ibb_nobetci_eczane	伊斯坦布尔今日值班药房：名称、县、地址、电话、位置；可按 ilce 筛选	İBB
ibb_otopark	İSPARK 停车场实时空位/占用情况；按县、名称或坐标查找最近的停车场	İBB
ibb_otopark_detay	某个 İSPARK 停车场的收费、地址、月度订阅费用	İBB
ibb_hava_kalitesi	28 个站点的 AQI、主要污染物、PM10/SO2/O3/NO2/CO；可查询单个站点的 24 小时序列	İBB
ibb_metro	Metro İstanbul 线路（首班/末班车）及某条线路按顺序排列的车站（电梯、卫生间……）	İBB
ibb_metro_duyurular	Metro İstanbul 乘客公告：故障、班次调整、车站关闭	İBB
izmir_nobetci_eczane	伊兹密尔今日值班药房，可按区域查询	İzmir BB
izmir_hal_fiyatlari	伊兹密尔批发市场每日蔬果/鱼类价格（最低、最高、平均）	İzmir BB
izmir_otobus	实时查询即将到达 ESHOT 站点的公交车：线路、剩余站数、位置	İzmir BB
acikveri_ara	在 İBB、伊兹密尔、科尼亚或加济安泰普开放数据门户中搜索数据集	4 个市政机构
acikveri_veriseti	数据集详情：许可证、文件、下载链接、是否提供表格服务	4 个市政机构
acikveri_kayitlar	查询开放表格服务数据集（DataStore）的列和行，支持分页和文本筛选	4 个市政机构
resmi_gazete_fihrist	当日 Resmî Gazete 目录：期号、部分/类型、条目标题和链接	Resmî Gazete
resmi_gazete_metin	某个条目（条例、公告、决定）的纯文本，按 2 万字符分块	Resmî Gazete
mevzuat_ara	搜索法律、法令、条例、公告、总统决定/总统令/通告（按标题或全文）	mevzuat.gov.tr
mevzuat_metin	某项法规的官方最新（合并）全文，附条款列表，分块返回	mevzuat.gov.tr
mevzuat_madde	单个条款：6、6/A、ek 1、geçici 3——附标题	mevzuat.gov.tr
resmi_tatiller	年度法定节假日：国家节日 + 根据 Diyanet 日历确定的宗教节日（包括节日前夕的半天假期）	无
tatil_mi	判断某日期是周末、节假日还是工作日	无
osym_sinav_takvimi	ÖSYM 日历：YKS、KPSS、ALES、YDS、DGS、TUS……的报名、考试、成绩和志愿填报日期；默认仅返回未来日期	ÖSYM
resmi_parametreler	年度官方数值及其来源：最低工资（日薪/月薪，税前、税后）、SGK 养老金缴费收入下限/上限	无
il_bilgisi	某省的人口、面积、海拔、车牌和区号、所属地区、按人口排序的县	无
ilce_ara	根据县名查询所属省份、人口、面积；返回所有同名县	无
iller_listesi	81 个省按人口/面积/车牌排序，可按地区筛选	无
dogrula_tckn	土耳其共和国身份证号码校验位验证	无
dogrula_vkn	税务识别号码校验位验证	无
dogrula_iban	TR IBAN mod-97 校验 + 银行代码	无
plaka_il	车牌代码 ↔ 省份，覆盖 81 个省	无
haber_basliklari	AA 或 TRT Haber 的最新新闻：标题、摘要、链接、时间；支持按类别筛选和搜索	AA、TRT
* EVDS 工具需要免费的个人密钥 — 参见 TCMB EVDS 密钥。如果没有密钥，这五个工具会返回一条说明如何获取密钥的错误，其他工具不受影响。

验证工具仅验证格式：会计算校验位，不会向任何机构查询，号码也不会离开本机。“有效”号码并不意味着它属于真实的个人或机构；每条响应都会明确说明这一点。

预设提示词

在客户端中显示为斜杠命令或菜单项：

提示词	功能
gunun_ozeti	一次性汇总汇率、地震、天气、交通和《官方公报》标题，生成 10 行每日摘要（il 为可选项）
mevzuat_sorusu	根据 mevzuat.gov.tr 的法规文本，提取并引用相关条款，附上来源以回答法律问题

TCMB EVDS 密钥

EVDS 是中央银行的统计服务（CPI、政策利率、汇率、房价指数、国际收支、调查 — 超过 40,000 个序列），需要免费的个人密钥：

1. 前往 https://evds3.tcmb.gov.tr → 我的页面 → 注册（验证电子邮件）。
2. 登录后，点击用户名下方的我的个人资料。
3. 点击页面底部的复制 API Key按钮。

在 MCP 配置中通过环境变量提供密钥：

{
  "mcpServers": {
    "turkiye": {
      "command": "npx",
      "args": ["-y", "mcp-turkiye"],
      "env": { "EVDS_API_KEY": "anahtarınız" }
    }
  }
}

密钥仅用于 EVDS 请求的 key 标头；不会出现在任何响应、日志或 URL 中。EVDS 每次请求最多返回 150 条观测值；要获取更长时间范围的数据，需要多次调用。

每条响应都包含在一个信封中

{
  "kaynak": { "id": "tcmb", "ad": "Türkiye Cumhuriyet Merkez Bankası", "url": "https://www.tcmb.gov.tr/kurlar/today.xml" },
  "alindi": "2026-09-16T13:40:12.000Z",
  "veri": { "tarih": "2026-09-16", "bultenNo": "2026/174", "kur": { "kod": "USD", "dovizSatis": 48.6654, "birim": 1 } }
}

kaynak 是数据来源机构和完整 URL，alindi 是数据获取时间。如果汇率或地震列表不带日期，就可能被误读为“永恒不变的事实”；信封可以避免这种情况。如果来源没有响应，工具会返回错误 — 绝不会生成估算值，并会说明哪个机构没有响应。

设计决策

• 每条响应都是实时的。 软件包中没有嵌入数据（节假日日历、车牌表和附带来源的嵌入式官方参数除外）；每次调用工具时，都会向机构获取数据。缓存仅用于保护机构，且时间很短：交通指数 1 分钟、地震 1 分钟、汇率 5 分钟、天气 10 分钟、燃油价格 30 分钟；alindi 字段会说明数据的确切获取时间。
• 无需密钥，无需注册。 所有来源都是公开的，无需密钥。需要免费密钥的来源（例如 TCMB EVDS）加入后将作为可选项；无需密钥即可运行的工具仍然无需密钥。
• 不让公共服务端过载。 每个请求都有超时限制，遇到 5xx 时重试一次，遇到 4xx 时不重试；相同 URL 会在短时间内缓存。昨天的公告不会变化，因此缓存一天；今天的公告缓存 5 分钟。
• 来源出现问题，我们会及时发现。 每周都会针对每个来源的实际端点运行契约测试（npm run test:live）；格式变更时，CI 会失败，以免助手向用户提供错误答案。
• 不处理个人数据。 不会使用或添加任何需要登录或个人数据的来源，例如 NVI 身份验证、e-Nabız、e-Devlet。
• 用自己的药。 此仓库中的示例客户端配置会在每次 CI 运行时通过 guardmcp 扫描。

路线图

后续候选项：İETT 线路／站点／班次（SOAP）、安卡拉／伊兹密尔水库蓄水量、TFF 积分榜、EPDK 电价、GİB 税务日历。由于 Diyanet 祷告时间需要官方 API 密钥，目前暂缓。添加一个来源只需添加一个文件夹：CONTRIBUTING.md。

开发

npm ci
npm run verify      # typecheck + lint + build + test (kapsama eşiği %80)
npm run test:live   # gerçek kaynaklara karşı sözleşme testleri
npm run dev         # stdio üzerinden sunucuyu çalıştır

English

面向 AI Agent 的土耳其公共数据，集于一个 MCP 服务。使用 npx -y mcp-turkiye 安装（需要 Node 20+，除可选的 EVDS 工具外，无需密钥）。目前提供 44 个工具：央行外汇公告（全部货币或单种货币，可查今日或任意过往日期）、BtcTurk 以里拉计价的实时加密货币价格、央行 EVDS 统计数据（主题树、数据组、序列和观测值，支持同比变化等公式；还可按名称查询主要指标——通胀、PPI、政策利率、外汇、房价指数、实际有效汇率；需要免费的 EVDS_API_KEY）、伊斯坦布尔证券交易所每日价格历史、AFAD 地震目录查询和 Kandilli Observatory 的独立列表、MGM 任意省或区的当前天气状况和 5 天预报及其生效中的恶劣天气预警、Opet 各区加油站油价、伊斯坦布尔实时交通指数、伊斯坦布尔和伊兹密尔今日值班药房、İSPARK 实时停车场占用情况（按距离由近到远排序）、伊斯坦布尔空气质量站点的 AQI 和污染物读数、伊斯坦布尔地铁线路、站点和运营公告、伊兹密尔实时 ESHOT 公交车及每日批发农产品和鱼类价格、伊斯坦布尔、伊兹密尔、科尼亚和加济安泰普的 CKAN 开放数据搜索/数据集/DataStore 访问、官方公报每日索引和文章正文、从 mevzuat.gov.tr 搜索法规、查询整合后的全文和单条法规、公共假日及 Diyanet 宗教节日日期、工作日检查、ÖSYM 全国考试日历（大学入学、公务员、研究生和语言考试）、官方年度数据（最低工资和社会保障缴费基数上下限，各附 Resmî Gazete 期号或法规）、离线省和区档案（人口、面积、车牌和区号、地区）、按类别获取 AA 和 TRT 最新头条，以及离线校验国家身份证号码、税号和 IBAN，并查询省份 ↔ 车牌代码。每个回答都包含数据来源机构、确切 URL 和获取时间；来源无响应时会返回工具错误，绝不猜测数值。工具说明提供双语版本，便于英语模型正确使用。如需远程托管，Docker 镜像 ghcr.io/berkantacun/mcp-turkiye 会在 /mcp 启动内置的无状态 Streamable HTTP 入口（node dist/http.js），并提供 /health；设置 MCP_TURKIYE_API_KEY 后，每个请求都需要 X-API-Key 标头，且请求会按 IP 限流（默认每分钟 60 次）。数据许可：SOURCES.md。可接受使用：ACCEPTABLE_USE.md。

许可证

代码：MIT。数据：遵循各来源自身的条款，详见 SOURCES.md。