MCP server for Destiny 2 API integration
npm install destiny2-mcp-serverProduction-ready Model Context Protocol (MCP) server for Destiny 2, providing player lookup, activity tracking, item/perk resolution via local manifest cache, clan roster access, and day-one triumph confidence scoring.
| Area | Capabilities |
|------|-------------|
| Players | Fuzzy/exact Bungie name search, profiles, characters, equipment |
| Activities | History with auto name resolution, PGCR, lifetime stats |
| Items | Full sockets/perks, plug sets, activity definitions, images (base64) |
| Clans | Direct roster lookup via cached groupId, elite rank scoring |
| Triumphs | Day-one/contest raid detection with weighted scoring |
| Prompts | Guided workflows for common queries |
Option 1: npm (Node.js required)
``bash`
npm install -g destiny2-mcp-server
Option 2: Docker (recommended for production)
`bash`
docker pull ghcr.io/nadiar/destiny2-mcp-server:latest
See Docker Deployment Guide for detailed Docker setup.
#### 1. Create Bungie API Application
Go to Bungie Developer Portal and create a new application:
Required Settings:
- Application Name: MCP Server for LLM (or your preferred name)Private
- Application Status: Not applicable
- OAuth Client Type: *
- Redirect URL: Leave empty
- Scope: Not applicable (server uses API key only, no OAuth)
- Origin Header:
After creating, copy your API Key (32-character hex string).
#### 2. Create .env file
`env`
BUNGIE_API_KEY=your-32-character-hex-key
`bashGlobal install
destiny2-mcp-server
MCP Client Configuration
$3
Add to claude_desktop_config.json:
`json
{
"mcpServers": {
"destiny2": {
"command": "destiny2-mcp-server",
"env": {
"BUNGIE_API_KEY": "your-api-key"
}
}
}
}
`$3
For Docker deployment, use:
`json
{
"mcpServers": {
"destiny2": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "BUNGIE_API_KEY=your-api-key-here",
"ghcr.io/nadiar/destiny2-mcp-server:latest"
]
}
}
}
`$3
For Docker MCP Gateway users, install via CLI:
Step 1: Create Custom Catalog
Create
~/.docker/mcp/catalogs/custom-servers.yaml:`yaml
version: 3
name: custom-servers
displayName: Custom MCP Servers
registry:
destiny2:
description: Production-ready Model Context Protocol (MCP) server for Destiny 2
title: Destiny 2
type: server
dateAdded: '2025-12-13T00:40:00Z'
image: ghcr.io/nadiar/destiny2-mcp-server:latest
ref: ''
icon: https://www.bungie.net/img/theme/destiny/icons/icon_d2.png
tools:
- name: search_player
- name: find_players
- name: get_profile
- name: get_character
- name: get_activity_history
- name: get_pgcr
- name: get_historical_stats
- name: search_items
- name: get_item_details
- name: get_activity_definition
- name: get_clan_roster
- name: get_item_image
secrets:
- name: destiny2.api_key
env: BUNGIE_API_KEY
example: your-32-character-hex-key
prompts: 0
resources: {}
metadata:
category: gaming
tags:
- destiny2
- bungie
- gaming
- api
license: MIT License
owner: Nadiar
`Step 2: Import and Enable
`bash
Import the custom catalog
docker mcp catalog import ~/.docker/mcp/catalogs/custom-servers.yamlEnable the server
docker mcp server enable destiny2Set your Bungie API key as a secret
docker mcp secret set destiny2.api_key=your-32-character-hex-keyVerify installation
docker mcp server ls
`Important: The secret name must be exactly
destiny2.api_key (matches the secrets[].name in the catalog). The Docker MCP Gateway will automatically inject this as the BUNGIE_API_KEY environment variable when starting the container.Updating:
`bash
Pull the latest image
docker pull ghcr.io/nadiar/destiny2-mcp-server:latestRestart your MCP client to use the new version
`Example Usage
Once configured, you can ask your AI assistant questions like:
$3
> "Find a player named Guardian"
`text
Found 3 players matching "Guardian":1. Guardian#1234 (Confidence: 92/100 - Very High)
ā” PRIMARY ACCOUNT: Steam (type: 3, id: 4611686018XXXXXXXXX)
All Platforms:
- Steam: 4611686018XXXXXXXXX ā” PRIMARY
- Xbox: 4611686018YYYYYYYYY (linked)
- PlayStation: 4611686018ZZZZZZZZ (linked)
- Playtime: 4,521 hours
- Last Played: 12/12/2025 (0 days ago)
- Triumph: 25,340 active / 489,230 lifetime
- Clan: Math Class [MATH] ā Elite
- Day-One Clears: 8 š
2. Guardian#5678 (Confidence: 23/100 - Low)
ā” PRIMARY ACCOUNT: PlayStation (type: 2, id: 4611686018XXXXXXXXX)
- Playtime: 12 hours
- Last Played: 03/15/2024 (633 days ago)
- No clan
`$3
> "How much time have they spent in Ghosts of the Deep?"
`text
Activity Statistics Summary
Analyzed 500 activities, sorted by time played
By Activity
$3
- Activities: 145 (127 completed, 87% completion rate)
- Total Time: 47h 23m
- Total Kills: 18,940
- Efficiency: 2.34
- Date Range: 02/15/2025 - 12/11/2025$3
- Activities: 98 (94 completed, 96% completion rate)
- Total Time: 38h 12m
- Date Range: 11/03/2024 - 12/10/2025$3
- Activities: 62 (61 completed, 98% completion rate)
- Total Time: 19h 47m---
Overall Totals
- Activities: 500
- Total Time: 115h 32m
- Date Range: 11/20/2021 - 12/11/2025
`$3
> "Get details on that Salvation's Edge run"
`text
Post-Game Carnage Report
Activity: Salvation's Edge (Master)
Date: 2025-11-28 19:32:15 UTC
Duration: 1h 23m 47sFireteam (6 players):
āāāāāāāāāāāāāāāāāāā¬āāāāāāāā¬āāāāāāāāā¬āāāāāāāāāā¬āāāāāāāāāāā
ā Player ā Kills ā Deaths ā Assists ā K/D ā
āāāāāāāāāāāāāāāāāāā¼āāāāāāāā¼āāāāāāāāā¼āāāāāāāāāā¼āāāāāāāāāāā¤
ā [REDACTED]#XXXX ā 187 ā 1 ā 42 ā 187.00 ā
ā [REDACTED]#XXXX ā 156 ā 0 ā 38 ā ā ā
ā [REDACTED]#XXXX ā 142 ā 2 ā 51 ā 71.00 ā
ā [REDACTED]#XXXX ā 138 ā 1 ā 44 ā 138.00 ā
ā [REDACTED]#XXXX ā 121 ā 0 ā 39 ā ā ā
ā [REDACTED]#XXXX ā 118 ā 0 ā 47 ā ā ā
āāāāāāāāāāāāāāāāāāā“āāāāāāāā“āāāāāāāāā“āāāāāāāāāā“āāāāāāāāāāā
Total Team Kills: 862
Total Team Deaths: 4
Completion: ā Success
`$3
> "What perks can roll on Fatebringer?"
`text
Fatebringer (Adept)
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Type: Hand Cannon (Kinetic)
Tier: Legendary
Source: Vault of GlassPerk Columns:
āāā Column 1: Explosive Payload, Firefly, Opening Shot, Frenzy
āāā Column 2: Tunnel Vision, Rewind Rounds, Kill Clip
āāā Barrel: Hammer-Forged, Smallbore, Corkscrew, Full Bore
āāā Magazine: Accurized Rounds, Tactical Mag, Appended Mag
Curated Roll: Explosive Payload + Firefly
`$3
> "Show me the Fatebringer screenshot"
The
get_item_image tool can return either:- Screenshot (default): Large inspect image (~200KB) - great for detailed weapon views
- Icon: Small inventory icon (~3KB) - useful for quick references
`text
Fatebringer
Screenshot[High-resolution weapon image displayed inline]
`Use
imageType: "icon" parameter for the small inventory icon instead.$3
> "Show me the roster for my clan"
`text
Clan: Example Clan [EXMP]
Members: 87/100Online Now (3):
⢠Player#0001 - Titan (Last: Tower)
⢠Player#0002 - Hunter (Last: Salvation's Edge)
⢠Player#0003 - Warlock (Last: Crucible)
Top by Playtime:
1. Player#0004 - 6,234 hours
2. Player#0005 - 5,891 hours
3. Player#0006 - 5,122 hours
`Available Tools
| Tool | Description |
|------|-------------|
|
search_player | Exact Bungie name lookup (requires #code) |
| find_players | Fuzzy search by partial name with confidence scores + cross-save primary detection |
| get_profile | Full player profile with characters, clan, triumph scores |
| get_character | Detailed character info and equipped gear |
| get_activity_history | Recent activities with time played |
| get_activity_stats | Aggregated activity statistics with pagination (up to 1000), customizable fields, and activity filtering |
| get_pgcr | Post-game carnage report with time data |
| get_historical_stats | Lifetime PvE/PvP statistics by activity |
| search_items | Search weapons/armor by name |
| get_item_details | Full item info with perks, stats, and plug sets |
| get_item_image | Item screenshot or icon (supports imageType parameter) |
| get_activity_definition | Activity/encounter details from manifest |
| get_clan_roster | Full clan member list with online status |
| get_plug_set | Available perks for specific weapon/armor slots |Releases and Updates
$3
Docker images and npm packages are automatically published on each release:
- Docker:
ghcr.io/nadiar/destiny2-mcp-server:latest or :1.2.4
- npm: npm install -g destiny2-mcp-server@latestView all releases: GitHub Releases
$3
npm installation:
`bash
npm update -g destiny2-mcp-server
`Docker installation:
`bash
Pull latest version
docker pull ghcr.io/nadiar/destiny2-mcp-server:latestOr pull specific version
docker pull ghcr.io/nadiar/destiny2-mcp-server:1.2.4
`After updating, restart your MCP client (Claude Desktop, etc.).
Documentation
- API Reference - Complete tool reference with examples
- Contributing Guide - How to contribute to the project
- Docker Deployment - Running with Docker
- Troubleshooting Guide - Common issues and solutions
Development
See CONTRIBUTING.md for development setup, testing, and contribution guidelines.
CI/CD
This project uses GitHub Actions for continuous integration and deployment:
- CI: Runs on every push and pull request
- Tests on Node.js 18, 20, and 22
- Linting and formatting checks
- Security audits
- Docker image builds
- Code coverage reports
- Release: Automated releases on version tags
- Publishes to npm registry
- Builds and pushes Docker images to GitHub Container Registry
- Creates GitHub releases with auto-generated notes
- Dependabot: Automated dependency updates
- Weekly checks for npm, GitHub Actions, and Docker base images
- Grouped minor/patch updates
- Security vulnerability alerts
Adding to MCP Toolkit Registry
To make this server discoverable in the MCP Toolkit Registry:
$3
`bash
Fork https://github.com/modelcontextprotocol/servers on GitHub
git clone https://github.com/YOUR_USERNAME/servers.git
cd servers
`$3
Create a new entry in
src/servers.json:`json
{
"name": "destiny2-mcp-server",
"description": "Destiny 2 API integration with player lookup, activity tracking, item/perk resolution, clan management, and day-one triumph scoring",
"repository": "https://github.com/Nadiar/destiny2-mcp-server",
"icon": "https://www.bungie.net/img/theme/destiny/icons/icon_d2.png",
"categories": ["gaming", "api"],
"installation": {
"npm": "destiny2-mcp-server",
"docker": "ghcr.io/nadiar/destiny2-mcp-server"
},
"configuration": {
"required": {
"BUNGIE_API_KEY": "Your Bungie API key from https://www.bungie.net/en/Application"
},
"optional": {
"LOG_LEVEL": "Logging level (debug, info, warn, error)",
"CACHE_TTL_HOURS": "Manifest cache TTL in hours (1-168)",
"API_RATE_LIMIT_MS": "Minimum ms between API requests (50-1000)"
}
},
"features": [
"Fuzzy player search by Bungie name",
"Activity history with automatic name resolution",
"Post-game carnage reports (PGCR)",
"Item/weapon perk lookups via local manifest cache",
"Clan roster management",
"Day-one raid completion detection",
"Item images (screenshots and icons)",
"Lifetime statistics tracking"
]
}
`$3
`bash
git checkout -b add-destiny2-mcp-server
git add src/servers.json
git commit -m "Add destiny2-mcp-server to registry"
git push origin add-destiny2-mcp-serverCreate PR on GitHub: https://github.com/modelcontextprotocol/servers
`$3
- Ensure all tests pass
- Server must be publicly available (npm/Docker)
- Documentation should be complete
- Follow the contribution guidelines
$3
Users can also add this server manually using the MCP toolkit:
`bash
Using npm
mcp install destiny2-mcp-serverOr add to Claude Desktop config manually (see MCP Client Configuration above)
``MIT - See LICENSE file for details.