AKShare MCP Server
by ttjslbz001
# AKShare MCP Server
A Model Context Protocol (MCP) server that provides financial data analysis capabilities using the AKShare library.
## Features
- Access to Chinese and global financial market data through AKShare
- Integration with Claude Desktop via MCP protocol
- Support for various financial data queries and analysis
## Installation
### Using uv (recommended)
```bash
# Clone the repository
git clone https://github.com/yourusername/akshare_mcp_server.git
cd akshare_mcp_server
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies with uv
uv pip install -e .
```
### Using pip
```bash
# Clone the repository
git clone https://github.com/yourusername/akshare_mcp_server.git
cd akshare_mcp_server
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -e .
```
## Usage
### Running the server
```bash
# Activate the virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the server
python run_server.py
```
### Integrating with Claude Desktop
1. Add the following configuration to your Claude Desktop configuration:
```json
"mcpServers": {
"akshare-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/akshare_mcp_server",
"run",
"akshare-mcp"
],
"env": {
"AKSHARE_API_KEY": "<your_api_key_if_needed>"
}
}
}
```
2. Restart Claude Desktop
3. Select the AKShare MCP server from the available tools
## Available Tools
The AKShare MCP server provides the following tools:
- Stock data queries
- Fund data queries
- Bond data queries
- Futures data queries
- Forex data queries
- Macroeconomic data queries
- And more...
## Adding a New Tool
To add a new tool to the MCP server, follow these steps:
1. **Add a new API function in `src/mcp_server_akshare/api.py`**:
```python
async def fetch_new_data_function(param1: str, param2: str = "default") -> List[Dict[str, Any]]:
"""
Fetch new data type.
Args:
param1: Description of param1
param2: Description of param2
"""
try:
df = ak.akshare_function_name(param1=param1, param2=param2)
return dataframe_to_dict(df)
except Exception as e:
logger.error(f"Error fetching new data: {e}")
raise
```
2. **Add the new tool to the enum in `src/mcp_server_akshare/server.py`**:
```python
class AKShareTools(str, Enum):
# Existing tools...
NEW_TOOL_NAME = "new_tool_name"
```
3. **Import the new function in `src/mcp_server_akshare/server.py`**:
```python
from .api import (
# Existing imports...
fetch_new_data_function,
)
```
4. **Add the tool definition to the `handle_list_tools()` function**:
```python
types.Tool(
name=AKShareTools.NEW_TOOL_NAME.value,
description="Description of the new tool",
inputSchema={
"type": "object",
"properties": {
"param1": {"type": "string", "description": "Description of param1"},
"param2": {"type": "string", "description": "Description of param2"},
},
"required": ["param1"], # List required parameters
},
),
```
5. **Add the tool handler in the `handle_call_tool()` function**:
```python
case AKShareTools.NEW_TOOL_NAME.value:
param1 = arguments.get("param1")
if not param1:
raise ValueError("Missing required argument: param1")
param2 = arguments.get("param2", "default")
result = await fetch_new_data_function(
param1=param1,
param2=param2,
)
```
6. **Test the new tool** by running the server and making a request to the new tool.
## Development
```bash
# Install development dependencies
uv pip install -e ".[dev]"
# Run tests
pytest
```
## Docker
You can also run the server using Docker:
```bash
# Build the Docker image
docker build -t akshare-mcp-server .
# Run the Docker container
docker run -p 8000:8000 akshare-mcp-server
```
## License
MIT