# Infoway MCP Server

MCP (Model Context Protocol) Server that gives Claude and other AI assistants access to real-time financial data through the [Infoway API](https://infoway.io). Query stock prices, crypto markets, forex, market sentiment, sector analysis, and company fundamentals -- all from within your AI conversation.

## Features

- **17 financial data tools** covering real-time quotes, K-line charts, market overview, sector analysis, and stock fundamentals
- **Multi-market support**: US, HK, CN, SG, JP, IN equities + crypto + forex
- **Zero configuration**: just add your API key and start asking questions
- Works with Claude Desktop, Cursor, and any MCP-compatible client

## Requirements

- Python 3.10+
- `mcp` 1.x — the server pins `mcp>=1.0,<2`. mcp 2.x removed the low-level handler
  decorators this server is built on, so an unpinned install resolves to 2.x and the
  server fails to start.
- `infoway-sdk` >= 0.2.0

## Installation

```bash
# Using uvx (recommended)
uvx infoway-mcp-server

# Using pip
pip install infoway-mcp-server
```

> Upgrading from 0.1.0? Do upgrade. 0.1.0 shipped without the `mcp<2` bound, so fresh
> installs pick up mcp 2.x and the server exits at import time — Claude Desktop shows it
> greyed out with no error. `pip install -U infoway-mcp-server` fixes it.

## Configuration

### Claude Desktop

Add the following to your Claude Desktop configuration file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "infoway": {
      "command": "uvx",
      "args": ["infoway-mcp-server"],
      "env": {
        "INFOWAY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "infoway": {
      "command": "uvx",
      "args": ["infoway-mcp-server"],
      "env": {
        "INFOWAY_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Available Tools

### Real-Time Market Data

| Tool | Description |
|------|-------------|
| `get_realtime_trade` | Latest trade per symbol: `s`, `t` (epoch ms), `p` (price), `v` (volume), `vw` (turnover), `td`. No percent-move field is returned |
| `get_market_depth` | Order book: `a` (asks) / `b` (bids), each column-oriented as `[[prices…],[quantities…]]` |
| `get_kline` | Candles under `respList` (1m to yearly). Multiple codes in one call are truncated by the server to **2 candles per product** — query one code at a time for history |

### Market Overview

| Tool | Description |
|------|-------------|
| `get_market_temperature` | Market sentiment and heat indicators for HK, US, CN, SG |
| `get_market_breadth` | Advance/decline statistics for a market |
| `get_global_indexes` | Real-time data for major global indexes (Dow, S&P, Nasdaq, HSI, etc.) |
| `get_leading_industries` | Top-performing industry sectors ranked by performance |

### Sector / Plate Analysis

| Tool | Description |
|------|-------------|
| `get_industry_list` | Full list of industry sectors with performance data |
| `get_concept_list` | Thematic/concept sectors (AI, EV, Metaverse, etc.) |
| `get_plate_members` | Stocks within a sector/plate. Paginated: takes `offset`/`limit`, returns `total` alongside `members` |
| `get_plate_heatmap` | Sector heatmap data for market visualization |

### Stock Fundamentals

| Tool | Description |
|------|-------------|
| `get_company_overview` | Company profile, description, CEO, headquarters, key metrics |
| `get_stock_valuation` | Valuation ratios: P/E, P/B, EV/EBITDA, dividend yield, market cap |
| `get_stock_ratings` | Analyst consensus: buy/sell/hold counts, target price |
| `get_stock_panorama` | Comprehensive stock summary with key financial data |
| `get_stock_drivers` | Key price drivers and catalysts affecting the stock |

### Utilities

| Tool | Description |
|------|-------------|
| `search_symbols` | List every instrument of one type. Requires `type` — one of `STOCK_US`, `STOCK_CN`, `STOCK_HK`, `STOCK_JP`, `STOCK_KS`, `STOCK_IN`, `CRYPTO`, `FOREX`, `FUTURES` (an instrument type, not a bare market code) |

## Symbol Conventions

| Market | Format | Example |
|--------|--------|---------|
| Hong Kong | **zero-padded to 5 digits** + `.HK` | `00700.HK` (`700.HK` is rejected with `All product not exists`) |
| US | ticker + `.US` | `AAPL.US` |
| China A-share | code + `.SH` / `.SZ` | `600519.SH` |
| Japan | code + `.JP` | `7203.JP` |
| India | ticker + `.IN` | `RELIANCE.IN` |
| Crypto | pair, no suffix | `BTCUSDT` |
| Forex / metals | pair, no suffix | `USDJPY`, `XAUUSD` |

## Example Conversations

Once configured, you can ask Claude questions like:

> **"What's the current price of Apple and Tesla?"**
> Claude will use `get_realtime_trade` with codes `AAPL.US,TSLA.US`

> **"Show me the daily K-line for Bitcoin over the last 30 days"**
> Claude will use `get_kline` with codes `BTCUSDT`, market_type `crypto`, kline_type 8, count 30

> **"How is the US market doing today? Which sectors are leading?"**
> Claude will use `get_market_temperature` and `get_leading_industries` for market `US`

> **"Give me a full analysis of Tencent"**
> Claude will combine `get_company_overview`, `get_stock_valuation`, `get_stock_ratings`, and `get_stock_drivers` for `00700.HK`

> **"Compare the valuation of NVIDIA vs AMD"**
> Claude will call `get_stock_valuation` for both `NVDA.US` and `AMD.US`

## Get Your API Key

Get your free API key at [infoway.io](https://infoway.io) -- includes a **7-day free trial** with full access to all endpoints.

## Development

```bash
# Clone and install in development mode
git clone https://github.com/infoway-api/infoway-mcp-server.git
cd infoway-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run the test suite (no API key needed -- fixtures are recorded production responses)
python -m pytest tests/ -q

# Run directly
infoway-mcp-server

# Or with Python
python -m infoway_mcp_server.server
```

`tests/test_smoke.py` is the dependency-drift guard: it imports the server, asserts the
installed `mcp` major version is still 1, and asserts all 17 tools register. If a future
dependency bump breaks the handler API again, that test fails instead of the tools
silently disappearing from Claude Desktop.

---

# Infoway MCP Server (中文)

MCP（模型上下文协议）服务器，让 Claude 和其他 AI 助手可以通过 [Infoway API](https://infoway.io) 访问实时金融数据。在 AI 对话中即可查询股票价格、加密货币行情、外汇、市场情绪、板块分析和公司基本面。

## 功能特点

- **17 个金融数据工具**，涵盖实时行情、K线图、市场概览、板块分析和个股基本面
- **多市场支持**：美股、港股、A股、新加坡、日本、印度 + 加密货币 + 外汇
- **零配置**：只需添加 API Key 即可开始使用
- 支持 Claude Desktop、Cursor 及所有兼容 MCP 协议的客户端

## 环境要求

- Python 3.10+
- `mcp` 1.x —— 本包已锁定 `mcp>=1.0,<2`。mcp 2.x 移除了本服务依赖的底层处理器装饰器，
  不锁上界会解析到 2.x，服务启动即失败。
- `infoway-sdk` >= 0.2.0

## 安装

```bash
# 使用 uvx（推荐）
uvx infoway-mcp-server

# 使用 pip
pip install infoway-mcp-server
```

> 如果你装的是 0.1.0，请务必升级：0.1.0 没有 `mcp<2` 上界，新装会拉到 mcp 2.x，
> 服务在 import 阶段就退出，Claude Desktop 里表现为服务变灰且没有任何报错。
> 执行 `pip install -U infoway-mcp-server` 即可修复。

## 配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "infoway": {
      "command": "uvx",
      "args": ["infoway-mcp-server"],
      "env": {
        "INFOWAY_API_KEY": "你的API密钥"
      }
    }
  }
}
```

## 工具列表

### 实时行情
- `get_realtime_trade` — 最新成交：`s`、`t`（毫秒时间戳）、`p`（价格）、`v`（成交量）、`vw`（成交额）、`td`；**不返回涨跌幅字段**
- `get_market_depth` — 盘口深度：`a`（卖）/`b`（买），均为列式 `[[价格…],[数量…]]`
- `get_kline` — K线数据在 `respList` 下，支持1分钟到年线；**一次传多个代码时服务端只返回每个产品 2 根**，要历史请逐个代码查询

### 市场概览
- `get_market_temperature` — 市场温度/情绪指标
- `get_market_breadth` — 市场涨跌统计
- `get_global_indexes` — 全球主要指数实时数据
- `get_leading_industries` — 领涨行业板块排名

### 板块分析
- `get_industry_list` — 行业板块列表及涨跌数据
- `get_concept_list` — 概念板块列表（AI、新能源车等）
- `get_plate_members` — 板块成分股列表；分页接口，入参 `offset`/`limit`，返回 `total` 与 `members`
- `get_plate_heatmap` — 板块热力图数据

### 个股基本面
- `get_company_overview` — 公司简介与基本信息
- `get_stock_valuation` — 估值指标（PE、PB、市值等）
- `get_stock_ratings` — 分析师评级与目标价
- `get_stock_panorama` — 个股全景数据概览
- `get_stock_drivers` — 股价驱动因素分析

### 其他
- `search_symbols` — 按品种类型列出全部交易标的；**必传 `type`**，取值为 `STOCK_US`、`STOCK_CN`、`STOCK_HK`、`STOCK_JP`、`STOCK_KS`、`STOCK_IN`、`CRYPTO`、`FOREX`、`FUTURES`（是品种类型，不是 `US`/`HK` 这类市场码）

## 代码格式约定

| 市场 | 格式 | 示例 |
|------|------|------|
| 港股 | **补零到 5 位** + `.HK` | `00700.HK`（`700.HK` 会报 `All product not exists`） |
| 美股 | 代码 + `.US` | `AAPL.US` |
| A股 | 代码 + `.SH` / `.SZ` | `600519.SH` |
| 日股 | 代码 + `.JP` | `7203.JP` |
| 印度 | 代码 + `.IN` | `RELIANCE.IN` |
| 加密货币 | 交易对，无后缀 | `BTCUSDT` |
| 外汇/贵金属 | 交易对，无后缀 | `USDJPY`、`XAUUSD` |

## 对话示例

> **"苹果和特斯拉现在什么价格？"**
> Claude 会调用 `get_realtime_trade`，代码 `AAPL.US,TSLA.US`

> **"看一下比特币最近30天的日K线"**
> Claude 会调用 `get_kline`，代码 `BTCUSDT`，market_type `crypto`

> **"今天美股表现怎么样？哪些板块领涨？"**
> Claude 会调用 `get_market_temperature` 和 `get_leading_industries`

> **"帮我全面分析一下腾讯"**
> Claude 会组合调用 `get_company_overview`、`get_stock_valuation`、`get_stock_ratings`、`get_stock_drivers`

## 获取 API Key

前往 [infoway.io](https://infoway.io) 免费注册获取 API Key，包含 **7天免费试用**，可访问全部接口。

## License

MIT