Lanyard MCP Server

A Model Context Protocol (MCP) server that provides Discord user presence information through the Lanyard API.

Purpose

This MCP server provides a secure interface for AI assistants to retrieve real-time Discord presence data, including online status, Spotify activity, Discord activities, and custom KV data for Discord users via the Lanyard service.

Features

Current Implementation

• get_user_presence - Get complete Discord presence information including status, platform info, Spotify, activities, and KV data

• get_user_spotify - Get detailed Spotify listening information with track details and timestamps

• get_user_kv - Retrieve custom Lanyard KV (key-value) data set by the user

All tools include:

• Input sanitization and validation for Discord user IDs

• Formatted, human-readable output with emojis

• Proper error handling for API failures

• Rate limit detection

• Timeout handling

Prerequisites

• Docker Desktop with MCP Toolkit enabled

• Docker MCP CLI plugin (docker mcp command)

• Discord user IDs (17-20 digit numbers) of users who are using Lanyard

Installation

Step 1: Build the Docker Image

docker build -t lanyard-mcp-server:latest .

Step 2: Configure MCP Catalog

Copy the custom catalog configuration:

# Copy custom.yaml to your Docker MCP catalogs directory
cp custom.yaml ~/.docker/mcp/catalogs/custom.yaml

Step 3: VS Code Integration (Optional)

If using Visual Studio Code with MCP support:

# Copy the MCP configuration to your project
cp .vscode/mcp.json /path/to/your/project/.vscode/

Step 4: Import and Enable the Server

# Import the catalog
docker mcp catalog import custom.yaml

# Enable the Lanyard server
docker mcp server enable lanyard

Agent Prompts

When working with AI agents that have access to this MCP server, you can use these example commands:

Get User Presence Information

docker mcp tools call get_user_presence user_id=77488778255540224

Get Spotify Activity

docker mcp tools call get_user_spotify user_id=77488778255540224

Get Custom KV Data

docker mcp tools call get_user_kv user_id=77488778255540224

Usage Examples

In Claude Desktop, you can ask:

• "What is the Discord presence for user 77488778255540224?"

• "Is user 77488778255540224 listening to Spotify?"

• "Show me the custom KV data for Discord user 77488778255540224"

• "Get the current status and activities for user 77488778255540224"

• "What song is user 77488778255540224 listening to on Spotify?"

What is Lanyard?

Lanyard is a service that exposes Discord user presence data through a REST API and WebSocket. Users must opt-in by joining the Lanyard Discord server. This MCP server uses the REST API to fetch user presence information.

Architecture

AI Agent → MCP Gateway → Lanyard MCP Server → Lanyard API ↓ Discord Presence Data

Development

Local Testing

# Run directly
python lanyard_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python lanyard_server.py

# Test with a known user ID (Lanyard creator)
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_user_presence","arguments":{"user_id":"94490510688792576"}},"id":2}' | python lanyard_server.py

Adding New Tools

1. Add the function to lanyard_server.py

2. Decorate with @mcp.tool()

3. Follow the pattern: single-line docstring, empty string defaults, return formatted string

4. Update the catalog entry with the new tool name

5. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully: docker images | grep lanyard

• Check catalog and registry files in ~/.docker/mcp/catalogs/

• Ensure Claude Desktop config includes custom catalog

• Restart Claude Desktop completely

"User not found" Errors

• Verify the Discord user ID is correct (17-20 digits)

• Ensure the user has joined the Lanyard Discord server

• Check that the user hasn't opted out of Lanyard

Rate Limit Errors

• Lanyard API has rate limits

• Wait a few moments before retrying

• Consider implementing caching if making frequent requests

API Reference

This server uses the Lanyard REST API:

• Base URL: https://api.lanyard.rest/v1

• Endpoint: GET /users/:user_id

• Documentation: https://github.com/Phineas/lanyard

Security Considerations

• No authentication required (Lanyard API is public)

• User IDs are validated and sanitized before use

• Running as non-root user in Docker

• Request timeouts prevent hanging

• No sensitive data stored or logged

Future Enhancement Ideas

• WebSocket support for real-time updates

• Caching to reduce API calls

• Batch user lookups

• Historical presence tracking

• Activity statistics

• Custom formatting options

Testing

94490510688792576 - Phineas (Lanyard creator) 77488778255540224 - b6d (MCP integration)

Find more users by joining the Lanyard Discord server.

Limitations

• Requires users to opt-in by joining Lanyard Discord

• Subject to Lanyard API rate limits

• No real-time updates (REST only, not WebSocket)

• Presence data depends on Discord API availability

Resources

• Lanyard GitHub: https://github.com/Phineas/lanyard

• Lanyard Discord: https://discord.gg/lanyard

• MCP Documentation: https://modelcontextprotocol.io