destiny2-mcp-server

v1.2.5

Published

13 days ago

MCP server for Destiny 2 API integration

0High
0Medium
0Low

nadiar

mcp model-context-protocol destiny2 bungie api gaming destiny llm ai

Destiny 2 MCP Server

Production-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.

Features

| 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 |

Quick Start

Installation

Option 1: npm (Node.js required)

npm install -g destiny2-mcp-server

Option 2: Docker (recommended for production)

docker pull ghcr.io/nadiar/destiny2-mcp-server:latest

See Docker Deployment Guide for detailed Docker setup.

Configuration

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)
Application Status: Private
OAuth Client Type: Not applicable
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

BUNGIE_API_KEY=your-32-character-hex-key

Running

# Global install
destiny2-mcp-server

# Or from source
npm install
npm run build
npm start

MCP Client Configuration

Claude Desktop (npm installation)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "destiny2": {
      "command": "destiny2-mcp-server",
      "env": {
        "BUNGIE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop (Docker)

For Docker deployment, use:

{
  "mcpServers": {
    "destiny2": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BUNGIE_API_KEY=your-api-key-here",
        "ghcr.io/nadiar/destiny2-mcp-server:latest"
      ]
    }
  }
}

Docker MCP Gateway

For Docker MCP Gateway users, install via CLI:

Step 1: Create Custom Catalog

Create ~/.docker/mcp/catalogs/custom-servers.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

# Import the custom catalog
docker mcp catalog import ~/.docker/mcp/catalogs/custom-servers.yaml

# Enable the server
docker mcp server enable destiny2

# Set your Bungie API key as a secret
docker mcp secret set destiny2.api_key=your-32-character-hex-key

# Verify 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:

# Pull the latest image
docker pull ghcr.io/nadiar/destiny2-mcp-server:latest

# Restart your MCP client to use the new version

Example Usage

Once configured, you can ask your AI assistant questions like:

Player Lookup

"Find a player named Guardian"

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

Activity History & Statistics

"How much time have they spent in Ghosts of the Deep?"

# Activity Statistics Summary

Analyzed 500 activities, sorted by time played

## By Activity

### Ghosts of the Deep
- 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

### Warlord's Ruin
- Activities: 98 (94 completed, 96% completion rate)
- Total Time: 38h 12m
- Date Range: 11/03/2024 - 12/10/2025

### Grasp of Avarice
- 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

Post-Game Carnage Report (PGCR)

"Get details on that Salvation's Edge run"

Post-Game Carnage Report
Activity: Salvation's Edge (Master)
Date: 2025-11-28 19:32:15 UTC
Duration: 1h 23m 47s

Fireteam (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

Item/Weapon Lookup

"What perks can roll on Fatebringer?"

Fatebringer (Adept)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Type: Hand Cannon (Kinetic)
Tier: Legendary
Source: Vault of Glass

Perk 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

Item Images

"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

# Fatebringer
*Screenshot*

[High-resolution weapon image displayed inline]

Use imageType: "icon" parameter for the small inventory icon instead.

Clan Roster

"Show me the roster for my clan"

Clan: Example Clan [EXMP]
Members: 87/100

Online 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

Latest Release

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@latest

View all releases: GitHub Releases

Updating

npm installation:

npm update -g destiny2-mcp-server

Docker installation:

# Pull latest version
docker pull ghcr.io/nadiar/destiny2-mcp-server:latest

# Or 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:

1. Fork the MCP Servers Repository

# Fork https://github.com/modelcontextprotocol/servers on GitHub
git clone https://github.com/YOUR_USERNAME/servers.git
cd servers

2. Add Server Entry

Create a new entry in src/servers.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. Submit Pull Request

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-server

# Create PR on GitHub: https://github.com/modelcontextprotocol/servers

4. PR Guidelines

Ensure all tests pass
Server must be publicly available (npm/Docker)
Documentation should be complete
Follow the contribution guidelines

Alternative: Use MCP Config Generator

Users can also add this server manually using the MCP toolkit:

# Using npm
mcp install destiny2-mcp-server

# Or add to Claude Desktop config manually (see MCP Client Configuration above)

License

MIT - See LICENSE file for details.