# Blue Archive MCP Server
A Model Context Protocol (MCP) server that provides comprehensive access to Blue Archive game data, including student information, equipment, stages, items, and more.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
## Overview
The Blue Archive MCP Server integrates with the SchaleDB API to provide AI assistants with real-time access to Blue Archive game data. This server implements the Model Context Protocol, enabling seamless integration with MCP-compatible clients like Claude Desktop.
### Key Capabilities
- **Student Database**: Access detailed information about all Blue Archive students
- **Equipment & Items**: Browse weapons, equipment, and consumable items
- **Stage Information**: Get details about campaign stages and raids
- **Multimedia Content**: Retrieve student avatars and voice clips
- **Advanced Search**: Filter and search across all data types
- **Multi-language Support**: Available in Chinese, Japanese, and English
## Features
- ā
**8 Comprehensive Tools** for accessing game data
- š **Multi-language Support** (CN/JP/EN)
- š **Advanced Filtering** and search capabilities
- š¼ļø **Rich Media Integration** (avatars, voice clips)
- ā” **Performance Optimized** with caching
- š”ļø **Error Handling** and retry mechanisms
- š± **Responsive Data Formatting** (text/markdown)
## Installation
### Prerequisites
- Node.js 18+
- npm or yarn package manager
- MCP-compatible client (e.g., Claude Desktop)
### Method 1: NPM Installation (Recommended)
Install directly from NPM:
```bash
npm install -g blue-archive-mcp
```
Or install locally in your project:
```bash
npm install blue-archive-mcp
```
### Method 2: From Source
1. **Clone the repository**
```bash
git clone <repository-url>
cd blue_archive_mcp
```
2. **Install dependencies**
```bash
npm install
```
3. **Build the project**
```bash
npm run build
```
4. **Test the server**
```bash
npm start
```
## Configuration
### Claude Desktop Integration
Add the following configuration to your Claude Desktop config file:
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
#### For NPM Installation:
```json
{
"mcpServers": {
"blue-archive": {
"command": "npx",
"args": ["blue-archive-mcp"]
}
}
}
```
#### For Source Installation:
```json
{
"mcpServers": {
"blue-archive": {
"command": "node",
"args": ["path/to/blue_archive_mcp/dist/index.js"]
}
}
}
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Logging level | `info` |
| `CACHE_TIMEOUT` | Cache timeout (ms) | `300000` |
## Available Tools
### 1. get_students
Retrieve student information with filtering options.
**Parameters:**
- `language` (string, optional): Language preference (cn/jp/en) - Default: "cn"
- `search` (string, optional): Search by student name
- `limit` (number, optional): Maximum results - Default: 20
- `detailed` (boolean, optional): Include detailed stats - Default: false
- `school` (string, optional): Filter by school
- `starGrade` (number, optional): Filter by star grade (1-3)
- `role` (string, optional): Filter by tactical role
### 2. get_student_info
Get detailed information for a specific student.
**Parameters:**
- `studentId` (number, required): Student's unique ID
- `language` (string, optional): Language preference - Default: "cn"
### 3. get_student_by_name
Find student by name (supports multiple languages).
**Parameters:**
- `name` (string, required): Student name in any supported language
- `language` (string, optional): Response language - Default: "cn"
- `detailed` (boolean, optional): Include detailed information - Default: false
### 4. get_raids
Retrieve raid information and boss data.
**Parameters:**
- `language` (string, optional): Language preference - Default: "cn"
- `search` (string, optional): Search by raid name
- `detailed` (boolean, optional): Include detailed stats - Default: false
### 5. get_equipment
Browse equipment and weapon data.
**Parameters:**
- `language` (string, optional): Language preference - Default: "cn"
- `category` (string, optional): Equipment category filter
- `tier` (number, optional): Equipment tier (1-7)
- `limit` (number, optional): Maximum results - Default: 20
- `detailed` (boolean, optional): Include detailed stats - Default: false
### 6. get_stages
Access campaign and stage information.
**Parameters:**
- `language` (string, optional): Language preference - Default: "cn"
- `search` (string, optional): Search by stage name
- `area` (string, optional): Filter by area
- `chapter` (string, optional): Filter by chapter
- `difficulty` (string, optional): Filter by difficulty
- `limit` (number, optional): Maximum results - Default: 20
- `detailed` (boolean, optional): Include detailed information - Default: false
### 7. get_items
Retrieve consumable items and materials.
**Parameters:**
- `language` (string, optional): Language preference - Default: "cn"
- `search` (string, optional): Search by item name
- `category` (string, optional): Item category filter
- `rarity` (number, optional): Item rarity (1-5)
- `tags` (string, optional): Filter by tags
- `limit` (number, optional): Maximum results - Default: 20
- `detailed` (boolean, optional): Include detailed information - Default: false
### 8. get_student_avatar
Get student avatar images in various formats.
**Parameters:**
- `studentId` (number, optional): Student's unique ID
- `name` (string, optional): Student name (alternative to ID)
- `language` (string, optional): Language preference - Default: "cn"
- `avatarType` (string, optional): Avatar type (portrait/collection/icon/lobby) - Default: "portrait"
- `format` (string, optional): Output format (markdown/md) - Default: "markdown"
## Usage Examples
### Basic Student Search
```
Find all students from Gehenna Academy
```
### Detailed Student Information
```
Get detailed information about Shiroko including stats and skills
```
### Equipment Browsing
```
Show me all tier 6 weapons with detailed stats
```
### Stage Information
```
Find all hard difficulty stages in chapter 3
```
### Avatar Display
```
Show me Hina's collection avatar in markdown format
```
## Development
### Project Structure
```
blue_archive_mcp/
āāā src/
ā āāā index.ts # Main server implementation
āāā dist/ # Compiled JavaScript output
āāā package.json # Project dependencies
āāā tsconfig.json # TypeScript configuration
āāā README.md # This file
```
### Building from Source
```bash
# Install dependencies
npm install
# Build TypeScript
npm run build
# Start development server
npm start
```
### Code Architecture
The server is built with:
- **TypeScript** for type safety and modern JavaScript features
- **@modelcontextprotocol/sdk** for MCP protocol implementation
- **Zod** for runtime type validation and schema generation
- **SchaleDB API** as the primary data source
### Key Components
- **BlueArchiveMCPServer**: Main server class handling MCP protocol
- **SchaleDBClient**: API client for data fetching
- **ErrorHandler**: Centralized error handling and logging
- **ParameterHandler**: Input validation and normalization
- **Logger**: Structured logging system
## Troubleshooting
### Common Issues
#### Connection Problems
- **Symptom**: Server fails to start or connect
- **Solution**: Check Node.js version (18+ required) and verify configuration paths
#### Data Loading Failures
- **Symptom**: API requests return empty results
- **Solution**: Verify internet connection and SchaleDB API availability
#### Tools Not Appearing
- **Symptom**: Tools don't show up in Claude Desktop
- **Solution**: Restart Claude Desktop after configuration changes
### Debug Mode
Enable debug logging by setting the environment variable:
```bash
LOG_LEVEL=debug npm start
```
### Performance Optimization
- Data is cached for 5 minutes by default
- Use `detailed=false` for faster responses when full data isn't needed
- Limit result sets with the `limit` parameter
## Contributing
We welcome contributions! Please follow these guidelines:
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request
### Development Guidelines
- Follow TypeScript best practices
- Add appropriate error handling
- Include JSDoc comments for new functions
- Test changes thoroughly before submitting
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Data Source
This server uses data from [SchaleDB](https://schaledb.com/), an open-source Blue Archive database. All game assets and data are property of their respective owners.
---
**Note**: This is an unofficial tool created by fans for the Blue Archive community. It is not affiliated with or endorsed by the game's official developers.
