jadenmong/akshare-mcp-server

AKShare MCP Server

|

A powerful financial data MCP (Model Context Protocol) server based on AKShare, providing AI assistants with comprehensive financial data retrieval capabilities.

🚀 Quick Start

Prerequisites

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

Installation

# 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

HTTP Version (Recommended):

• ✅ No Python or akshare installation required
• ✅ Based on HTTP API, stable and reliable
• ✅ Built-in fallback data ensures availability
• ✅ Simple deployment

Python Version:

• ✅ More comprehensive and complete data
• ❌ Requires local Python environment
• ❌ Depends on 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

{
  "mcpServers": {
    "akshare": {
      "command": "node",
      "args": ["E:\\akshare-mcp-server\\src\\server.js"],
      "env": {},
      "description": "AKShare Financial Data MCP Server"
    }
  }
}

Note: Please update the path E:\\akshare-mcp-server\\src\\server.js to your actual project path.

📋 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

🏗️ Project Structure

akshare-mcp-server/
├── src/
│   ├── server.js              # Python-based MCP server
│   ├── http-server.js         # HTTP-based MCP server (recommended)
│   └── tools/                 # Financial data tool modules
├── test/
│   └── test_client.js         # Test client
├── requirements.txt           # Python dependencies
├── package.json               # Node.js configuration
├── README.md                  # English documentation
├── README_CN.md              # Chinese documentation
└── LICENSE                    # Open source license

📝 Usage Examples

Stock Data Examples

Get Stock Historical Data

{
  "name": "get_stock_historical_data",
  "arguments": {
    "symbol": "000001",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131",
    "adjust": "qfq"
  }
}

Get Stock Real-time Quotes

{
  "name": "get_stock_realtime_data",
  "arguments": {
    "symbol": "000001"
  }
}

Get Stock List

{
  "name": "get_stock_list",
  "arguments": {
    "market": "all"
  }
}

Fund Data Examples

Get Fund Information

{
  "name": "get_fund_info",
  "arguments": {
    "symbol": "510050"
  }
}

Get Fund List

{
  "name": "get_fund_list",
  "arguments": {
    "type": "etf"
  }
}

Futures Data Examples

Get Futures Information

{
  "name": "get_futures_info",
  "arguments": {
    "symbol": "ag",
    "exchange": "SHFE"
  }
}

Economic Data Examples

Get Economic Indicators

{
  "name": "get_economic_data",
  "arguments": {
    "indicator": "GDP",
    "start_date": "20240101",
    "end_date": "20241231"
  }
}

🔧 Development and Testing

Run Tests

npm test

Development Mode (with auto-restart)

npm run dev

🔍 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

   # 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
   • Confirm that the server.js file path exists
   • Restart the Claude Desktop application

4. Data Retrieval Failed

   • Check network connection
   • Confirm AKShare library is working properly
   • Check server log output

Debug Mode

Start the server with detailed logging:

DEBUG=akshare:* npm start

🔧 Technical Features

• ⚡ High Performance: Asynchronous processing with concurrent request support
• 🛡️ Type Safety: Strict parameter validation using Zod
• 🌉 Python Bridge: Call AKShare library through subprocess
• 🔧 Modular Design: Tools organized by financial product category
• 📊 Data Standardization: Unified data format and error handling
• 🚀 Easy to Extend: Simple tool definition and addition mechanism

📄 License

This project is open source under the MIT License.

🙏 Acknowledgments

• AKShare - Powerful financial data API library
• Model Context Protocol - 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 section of this documentation
2. Submit an Issue on GitHub
3. Check the AKShare official documentation

📚 Documentation

• For detailed documentation in Chinese, see
• For the original AKShare documentation, visit AKShare GitHub