npm install destiny2-mcp-server

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

$3

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.

`$3`

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

`env BUNGIE_API_KEY=your-32-character-hex-key`

`$3`

`bash

`Global install`


destiny2-mcp-server
Or from source

npm install
npm run build
npm start


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

`bash

`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:
$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 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`

`$3`

> "What perks can roll on Fatebringer?"

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

`$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/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`

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

View 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: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:
$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-server

`Create 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-server
Or add to Claude Desktop config manually (see MCP Client Configuration above)

License

MIT - See LICENSE file for details.

npm install destiny2-mcp-server

Destiny 2 MCP Server

Features

Quick Start

$3

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.

`$3`

#### 1. Create Bungie API Application

Go to Bungie Developer Portal and create a new application:

Required Settings:

After creating, copy your API Key (32-character hex string).

#### 2. Create .env file

`env BUNGIE_API_KEY=your-32-character-hex-key`

`$3`

`bash

`Global install`


destiny2-mcp-server
Or from source

npm install
npm run build
npm start


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:

Step 2: Import and Enable

`bash

`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

Updating:

`bash

`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:
$3
> "Find a player named Guardian"

`text Found 3 players matching "Guardian":

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

Total Team Kills: 862 Total Team Deaths: 4 Completion: ✓ Success`

`$3`

> "What perks can roll on Fatebringer?"

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

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

View 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: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:
$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:

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

`Create 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-server
Or add to Claude Desktop config manually (see MCP Client Configuration above)

License

MIT - See LICENSE file for details.