# AKShare MCP Server

[English](./README.md) | [中文版](./README_CN.md)

A financial data MCP (Model Context Protocol) server based on AKShare, providing Claude and other AI assistants with comprehensive Chinese financial market data retrieval capabilities. Supports stocks, funds, futures, economic indicators, and more.

## 🚀 Quick Start

### Prerequisites

- **Node.js**: 18.0.0 or higher
- **Python**: 3.8 or higher (only required for Python version)

### Installation

```bash
# 1. Clone the project
git clone https://github.com/jadenmong/akshare-mcp-server.git
cd akshare-mcp-server

# 2. Install Node.js dependencies
npm install

# 3. Start the server (HTTP version, recommended - no Python dependencies)
npm start

# Or start Python version (requires Python and akshare installation)
npm run start:python
```

### Version Information

The project provides two MCP server implementations:

**HTTP Version (Recommended)**:
- ✅ Zero Python dependencies, ready to use
- ✅ Based on AKShare HTTP API, stable and reliable
- ✅ Built-in fallback data ensures service availability
- ✅ Simple deployment, fast startup

**Python Version**:
- ✅ Direct AKShare library calls, richer data
- ✅ Supports more data types (futures, economic indicators)
- ❌ Requires local Python 3.8+ environment
- ❌ Requires akshare library installation

## ⚙️ Configuration

### Claude Desktop Configuration

Add the following configuration to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`

**HTTP Version Configuration (Recommended)**:
```json
{
  "mcpServers": {
    "akshare": {
      "command": "node",
      "args": ["<your-project-path>/src/http-server.js"],
      "description": "AKShare Financial Data MCP Server (HTTP)"
    }
  }
}
```

**Python Version Configuration**:
```json
{
  "mcpServers": {
    "akshare": {
      "command": "node",
      "args": ["<your-project-path>/src/server.js"],
      "description": "AKShare Financial Data MCP Server (Python)"
    }
  }
}
```

**Note**: 
- Replace `<your-project-path>` with your actual absolute path
- Windows: use double backslashes `\\`, e.g., `D:\\projects\\akshare-mcp-server\\src\\http-server.js`
- macOS/Linux: use forward slashes `/`, e.g., `/home/user/akshare-mcp-server/src/http-server.js`

## 📋 Available Tools

### 📈 Stock Data (HTTP + Python Versions)
- **Historical Data**: `get_stock_historical_data` - Get stock historical data
- **Real-time Quotes**: `get_stock_realtime_data` - Get stock real-time quotes
- **Stock List**: `get_stock_list` - Get stock list

### 🔍 Search Tools (HTTP Version New)
- **Stock Search**: `search_stock` - Search stock information

### 💰 Fund Data (HTTP + Python Versions)
- **Fund List**: `get_fund_list` - Get fund list

### 📊 Futures Data (Python Version Only)
- **Futures Information**: `get_futures_info` - Get futures market data

### 🏭 Economic Data (Python Version Only)
- **Economic Indicators**: `get_economic_data` - Get macroeconomic data

### Version Comparison

| Feature | HTTP Version | Python Version |
|---------|--------------|----------------|
| Stock Historical Data | ✅ | ✅ |
| Stock Real-time Data | ✅ | ✅ |
| Stock List | ✅ | ✅ |
| Stock Search | ✅ | ❌ |
| Fund Data | ✅ | ✅ |
| Futures Data | ❌ | ✅ |
| Economic Data | ❌ | ✅ |

## 🏗️ Project Structure

```
akshare-mcp-server/
├── src/
│   ├── http-server.js         # HTTP version MCP server (recommended)
│   ├── server.js              # Python version MCP server
│   ├── tools/                 # Financial data tool modules
│   │   ├── stock_tools.js     # Stock data tools
│   │   ├── fund_tools.js      # Fund data tools
│   │   ├── futures_tools.js   # Futures data tools
│   │   └── economic_tools.js  # Economic data tools
│   └── utils/
│       └── toolHelpers.js     # Tool helper functions
├── test/
│   └── test.js                # Automated test suite
├── python_bridge.py           # Python bridge script
├── requirements.txt           # Python dependencies
├── package.json               # Node.js configuration
├── README.md                  # English documentation
├── README_CN.md               # Chinese documentation
└── LICENSE                    # MIT License
```

## 📝 Usage Examples

### Stock Data Examples

#### Get Stock Historical Data
```json
{
  "name": "get_stock_historical_data",
  "arguments": {
    "symbol": "000001",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131",
    "adjust": "qfq"
  }
}
```

#### Get Stock Real-time Quotes
```json
{
  "name": "get_stock_realtime_data",
  "arguments": {
    "symbol": "000001"
  }
}
```

#### Get Stock List
```json
{
  "name": "get_stock_list",
  "arguments": {
    "market": "all"
  }
}
```

### Fund Data Examples

#### Get Fund Information
```json
{
  "name": "get_fund_info",
  "arguments": {
    "symbol": "510050"
  }
}
```

#### Get Fund List
```json
{
  "name": "get_fund_list",
  "arguments": {
    "type": "etf"
  }
}
```

### Futures Data Examples

#### Get Futures Information
```json
{
  "name": "get_futures_info",
  "arguments": {
    "symbol": "ag",
    "exchange": "SHFE"
  }
}
```

### Economic Data Examples

#### Get Economic Indicators
```json
{
  "name": "get_economic_data",
  "arguments": {
    "indicator": "GDP",
    "start_date": "20240101",
    "end_date": "20241231"
  }
}
```

## 🔧 Development and Testing

### Run Tests

The project includes a comprehensive automated test suite for both versions:

```bash
npm test
```

Test coverage includes:
- Tool list retrieval
- Stock historical data queries
- Stock real-time quotes
- Stock list retrieval
- Fund data queries
- Futures data queries (Python version)
- Economic data queries (Python version)

### Development Mode (with auto-restart)

```bash
# HTTP version development mode
npm run dev

# Python version development mode
npm run dev:python
```

## 🔍 Troubleshooting

### Common Issues

1. **Node.js Version Too Low**
   ```
   Error: Node.js version 18.0.0 or higher required
   Solution: Upgrade Node.js to the latest LTS version
   ```

2. **Python Dependencies Installation Failed**
   ```bash
   # Try using a domestic mirror
   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
   ```

3. **Claude Desktop Connection Failed**
   - Check if the configuration file path is correct (note Windows uses double backslashes)
   - Confirm that `http-server.js` or `server.js` file path exists
   - Restart the Claude Desktop application
   - Check Claude Desktop log output

4. **Data Retrieval Failed**
   - Check network connection
   - HTTP version: Confirm access to AKShare HTTP API
   - Python version: Confirm akshare library is installed (`pip list | grep akshare`)
   - Check server log output for errors

### Debug Mode

Start the server with detailed logging:
```bash
DEBUG=akshare:* npm start
```

## 🔧 Technical Features

- ⚡ **High Performance**: Node.js async processing with concurrent request support
- 🛡️ **Type Safety**: Strict parameter validation and type checking using Zod
- 🌉 **Python Bridge**: Secure AKShare Python library calls via subprocess
- 🔧 **Modular Design**: Tools organized by financial product category for easy maintenance
- 📊 **Data Standardization**: Unified JSON data format and error handling
- 🚀 **Easy to Extend**: Simple tool definition and addition mechanism for rapid integration
- 🔄 **Dual Implementation**: HTTP and Python versions for different use cases
- ✅ **Comprehensive Testing**: Automated test suite ensures code quality

## 📄 License

This project is open source under the MIT License.

## 🙏 Acknowledgments

- [AKShare](https://github.com/akfamily/akshare) - Powerful financial data API library
- [Model Context Protocol](https://modelcontextprotocol.io/) - Standardized tool interface protocol

## 🤝 Contributing

Welcome to submit Issues and Pull Requests to improve this project!

## 📞 Support

If you encounter issues during use, please:
1. Check the [Troubleshooting](#-troubleshooting) section of this documentation
2. Submit an issue on [GitHub Issues](https://github.com/jadenmong/akshare-mcp-server/issues)
3. Consult the [AKShare Official Documentation](https://akshare.akfamily.xyz/)

## 📚 Related Documentation

- English Documentation: [README.md](./README.md) (this document)
- Chinese Documentation: [README_CN.md](./README_CN.md)
- AKShare Documentation: [AKShare Official Docs](https://akshare.akfamily.xyz/)
- MCP Protocol: [Model Context Protocol](https://modelcontextprotocol.io/)

## 🌟 Roadmap

- [ ] Support more financial data types (bonds, forex, cryptocurrency)
- [ ] Add data caching mechanism for better performance
- [ ] Support custom data source configuration
- [ ] Provide Docker image for simplified deployment
- [ ] Add data visualization tool integration