Metadata-Version: 2.4
Name: akshare-mcp-ikouhaha
Version: 0.4.0
Summary: Simple XAUUSD Gold Data MCP Server using AkShare
Project-URL: Homepage, https://github.com/your-username/akshare-mcp
Project-URL: Repository, https://github.com/your-username/akshare-mcp
Project-URL: Issues, https://github.com/your-username/akshare-mcp/issues
Author-email: Akshare MCP Team <akshare.mcp@example.com>
License: MIT License
        
        Copyright (c) 2024 Akshare MCP Server
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.10
Requires-Dist: aiosmtplib>=3.0.0
Requires-Dist: akshare>=1.12.0
Requires-Dist: mcp
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: mypy>=0.910; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
Requires-Dist: pytest>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Akshare MCP Server

[English](#english) | [中文](#中文)

## 中文

### 简介

Akshare MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的服务器，提供中国金融数据接口。通过集成 [akshare](https://github.com/akfamily/akshare) 库，为 Claude 等 AI 助手提供实时和历史的股票、期货、基金等金融数据。

### 功能特性

- 📈 **股票数据**：支持 A股股票的分钟级（5分钟、15分钟、30分钟、60分钟）和日线数据
- 🥇 **期货数据**：支持期货合约的分钟级和日线数据，包括黄金、白银等主力合约
- 💰 **黄金数据**：专门的黄金期货和现货数据接口
- 🔍 **股票搜索**：根据股票名称或代码搜索股票信息
- 📊 **市场概览**：提供 A股市场的整体概况和主要指数
- 🔄 **实时数据**：支持最新的交易数据和历史数据查询

### 安装

#### 使用 uvx（推荐）

```bash
uvx akshare-mcp-ikouhaha
```

#### 使用 pip

```bash
pip install akshare-mcp-ikouhaha
```

#### 从源码安装

```bash
git clone https://github.com/your-username/akshare-mcp.git
cd akshare-mcp
pip install -e .
```

### 配置

在你的 MCP 客户端配置文件中添加服务器配置：

```json
{
  "mcpServers": {
    "akshare": {
      "command": "akshare-mcp-ikouhaha"
    }
  }
}
```

### 使用示例

#### 获取股票数据

```python
# 获取平安银行（000001）的日线数据
get_stock_data({"symbol": "000001", "period": "daily"})

# 获取5分钟数据
get_stock_data({"symbol": "000001", "period": "5min", "adjust": "qfq"})
```

#### 获取期货数据

```python
# 获取黄金主力合约数据
get_futures_data({"symbol": "AU0", "period": "daily"})

# 获取5分钟期货数据
get_futures_data({"symbol": "AU0", "period": "5min"})
```

#### 搜索股票

```python
# 搜索包含"平安"的股票
search_stock({"keyword": "平安"})

# 根据股票代码搜索
search_stock({"keyword": "000001"})
```

### API 文档

#### 工具列表

1. **get_stock_data** - 获取股票数据
   - `symbol` (必需): 股票代码，如 "000001"
   - `period` (可选): 数据周期 ["5min", "15min", "30min", "60min", "daily", "weekly", "monthly"]，默认 "daily"
   - `adjust` (可选): 复权类型 ["qfq", "hfq", ""]，默认 "qfq"

2. **get_futures_data** - 获取期货数据
   - `symbol` (必需): 期货代码，如 "AU0"（黄金主力）
   - `period` (可选): 数据周期 ["5min", "15min", "30min", "60min", "daily"]，默认 "daily"

3. **get_gold_data** - 获取黄金数据
   - `data_type` (可选): 数据类型 ["futures", "spot", "futures_5min"]，默认 "futures"
   - `period` (可选): 数据周期，默认 "daily"

4. **get_market_overview** - 获取市场概览
   - `market` (可选): 市场类型 ["a_share", "us", "hk"]，默认 "a_share"

5. **search_stock** - 搜索股票
   - `keyword` (必需): 搜索关键词

### 开发

#### 环境设置

```bash
git clone https://github.com/your-username/akshare-mcp.git
cd akshare-mcp
pip install -e ".[dev]"
```

#### 运行测试

```bash
pytest
```

#### 代码格式化

```bash
black src/
isort src/
```

### 依赖项

- Python >= 3.8
- mcp >= 1.0.0
- akshare >= 1.12.0
- pandas >= 1.3.0

### 许可证

MIT License

---

## English

### Introduction

Akshare MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides Chinese financial data interfaces. By integrating the [akshare](https://github.com/akfamily/akshare) library, it offers real-time and historical data for stocks, futures, funds, and other financial instruments to AI assistants like Claude.

### Features

- 📈 **Stock Data**: Supports minute-level (5min, 15min, 30min, 60min) and daily data for A-share stocks
- 🥇 **Futures Data**: Supports minute-level and daily data for futures contracts, including gold and silver main contracts
- 💰 **Gold Data**: Dedicated gold futures and spot data interfaces
- 🔍 **Stock Search**: Search stock information by name or symbol
- 📊 **Market Overview**: Provides A-share market overview and major indices
- 🔄 **Real-time Data**: Supports latest trading data and historical data queries

### Installation

#### Using uvx (Recommended)

```bash
uvx akshare-mcp-ikouhaha
```

#### Using pip

```bash
pip install akshare-mcp-ikouhaha
```

#### From Source

```bash
git clone https://github.com/your-username/akshare-mcp.git
cd akshare-mcp
pip install -e .
```

### Configuration

Add the server configuration to your MCP client configuration file:

```json
{
  "mcpServers": {
    "akshare": {
      "command": "akshare-mcp-ikouhaha"
    }
  }
}
```

### Usage Examples

#### Get Stock Data

```python
# Get daily data for Ping An Bank (000001)
get_stock_data({"symbol": "000001", "period": "daily"})

# Get 5-minute data
get_stock_data({"symbol": "000001", "period": "5min", "adjust": "qfq"})
```

#### Get Futures Data

```python
# Get gold main contract data
get_futures_data({"symbol": "AU0", "period": "daily"})

# Get 5-minute futures data
get_futures_data({"symbol": "AU0", "period": "5min"})
```

#### Search Stocks

```python
# Search stocks containing "平安"
search_stock({"keyword": "平安"})

# Search by stock code
search_stock({"keyword": "000001"})
```

### API Reference

#### Tools

1. **get_stock_data** - Get stock data
   - `symbol` (required): Stock symbol, e.g., "000001"
   - `period` (optional): Data period ["5min", "15min", "30min", "60min", "daily", "weekly", "monthly"], default "daily"
   - `adjust` (optional): Adjustment type ["qfq", "hfq", ""], default "qfq"

2. **get_futures_data** - Get futures data
   - `symbol` (required): Futures symbol, e.g., "AU0" (Gold main)
   - `period` (optional): Data period ["5min", "15min", "30min", "60min", "daily"], default "daily"

3. **get_gold_data** - Get gold data
   - `data_type` (optional): Data type ["futures", "spot", "futures_5min"], default "futures"
   - `period` (optional): Data period, default "daily"

4. **get_market_overview** - Get market overview
   - `market` (optional): Market type ["a_share", "us", "hk"], default "a_share"

5. **search_stock** - Search stocks
   - `keyword` (required): Search keyword

### Development

#### Setup

```bash
git clone https://github.com/your-username/akshare-mcp.git
cd akshare-mcp
pip install -e ".[dev]"
```

#### Run Tests

```bash
pytest
```

#### Format Code

```bash
black src/
isort src/
```

### Dependencies

- Python >= 3.8
- mcp >= 1.0.0
- akshare >= 1.12.0
- pandas >= 1.3.0

### License

MIT License