Uses .env files for configuration management, allowing customization of API credentials and server settings.
Enables integration with GitHub for issue tracking, discussions, and reporting bugs for the MCP server through GitHub Issues and GitHub Discussions.
Supports Laravel Sanctum authentication for secure API communication with the IssueBadge platform.
Built on Node.js runtime, allowing for deployment in Node.js environments with version 18+ required.
Available as an npm package for easy installation and dependency management with npm version 8+ required.
Uses TypeScript for type-safe implementation, providing better code quality and developer experience when extending or modifying the MCP server.
IssueBadge MCP Server
A Model Context Protocol (MCP) server for interacting with the IssueBadge API. This server enables AI assistants like Claude and ChatGPT to manage digital badges and certificates using natural language.
🌟 Features
🤖 AI-Powered Badge Management: Use natural language to create, issue, and manage badges
🔐 Dual Authentication: Support for both Laravel Sanctum and OAuth2
🏆 Complete Badge Lifecycle: Create templates, issue to recipients, and verify authenticity
📊 Multi-tenant Support: Secure tenant isolation for enterprise use
🛡️ Idempotency Protection: Prevent duplicate operations with built-in safeguards
📧 Automated Notifications: Automatic email delivery with verification URLs
🎨 Custom Fields: Flexible metadata and custom field support
🚀 Quick Start
Prerequisites
Node.js 18+
npm 8+
IssueBadge API account with API key
Installation
Clone the repository
git clone https://github.com/issuebadge/mcp-server.git cd mcp-serverInstall dependencies
npm installConfigure environment
cp .env.example .env # Edit .env with your IssueBadge API credentialsBuild the project
npm run buildTest the server
npm test
⚙️ Configuration
Create a .env
file based on .env.example
:
🔧 Integration
Claude Desktop
Add this server to your Claude Desktop configuration:
ChatGPT Actions
Create a new Custom GPT in ChatGPT
Import the OpenAPI specification from your IssueBadge instance
Configure Bearer token authentication with your API key
Start managing badges through conversation!
🛠️ Available Tools
1. validate_key
Validates IssueBadge API keys for authentication.
Parameters:
api_key
(string, required): The API key to validate
Example:
2. get_all_badges
Retrieves all available badges for the authenticated organization.
Parameters:
limit
(number, optional): Maximum badges to return (default: 100)
Example:
3. create_badge
Creates a new badge template with optional custom fields.
Parameters:
name
(string, required): Badge namedescription
(string, required): Badge descriptionissuing_organization_name
(string, required): Organization nameidempotency_key
(string, required): Unique identifiercustom_fields
(array, optional): Custom field definitionsAnd more optional parameters...
Example:
4. issue_badge
Issues a badge to a recipient with optional metadata.
Parameters:
badge_id
(string, required): Badge ID from creationname
(string, required): Recipient's full nameidempotency_key
(string, required): Unique identifieremail
(string, optional): Recipient's emailmetadata
(object, optional): Custom field values
Example:
💬 Natural Language Examples
Creating Badges
Issuing Badges
Batch Operations
🏗️ Development
Building from Source
Project Structure
🔒 Security
All API communications use HTTPS
API keys are validated before each request
Idempotency keys prevent duplicate operations
Multi-tenant data isolation
Request timeout protection
Comprehensive error handling
📊 Error Handling
The MCP server provides detailed error messages for common issues:
Authentication Errors: Invalid API keys or expired tokens
Validation Errors: Missing required parameters or invalid formats
Network Errors: Connection timeouts or service unavailability
Business Logic Errors: Duplicate operations or insufficient permissions
🌍 Use Cases
Educational Institutions
Course Completion: Automatically issue badges when students complete courses
Skill Validation: Create skill-based badges with assessment scores
Graduation Certificates: Bulk issue graduation badges with academic details
Corporate Training
Certification Programs: Manage professional certifications with expiration dates
Compliance Training: Track and verify mandatory training completion
Skill Development: Issue badges for internal skill development programs
Event Management
Conference Attendance: Issue attendance badges for events and workshops
Achievement Tracking: Create progressive badge systems for ongoing programs
Speaker Recognition: Manage speaker and participant recognition badges
🤝 Contributing
We welcome contributions! Please see our contributing guidelines:
Fork the repository
Create a feature branch:
git checkout -b feature/amazing-feature
Commit your changes:
git commit -m 'Add amazing feature'
Push to the branch:
git push origin feature/amazing-feature
Open a Pull Request
Development Guidelines
Follow TypeScript best practices
Add comprehensive error handling
Include JSDoc comments for functions
Update tests for new features
Follow semantic versioning
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
🆘 Support
Getting Help
📖 Documentation: Check this README and inline code comments
🐛 Bug Reports: Open an issue
💬 Discussions: GitHub Discussions
📧 Email: support@issuebadge.com
Troubleshooting
Common Issues
1. API Key Validation Failed
2. Connection Timeout
3. Badge Creation Errors
🔗 Related Projects
IssueBadge API: Core badge management platform
Model Context Protocol: MCP specification and tools
Claude Desktop: AI assistant with MCP support
📈 Roadmap
Version 1.1
Batch badge operations
Advanced filtering and search
Webhook integration
Badge template management
Version 1.2
Analytics and reporting tools
Custom badge validation rules
Integration with learning management systems
Advanced workflow automation
Version 2.0
Blockchain verification support
Multi-language badge content
Advanced branding customization
Enterprise SSO integration
Ready to revolutionize your badge management? Get started with IssueBadge MCP Server and experience the power of conversational badge administration!
Built with ❤️ by the IssueBadge team
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that enables AI assistants to create, issue, and manage digital badges and certificates using natural language.
Related MCP Servers
- -securityFlicense-qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.Last updated -18
- AsecurityFlicenseAqualityA Model Context Protocol server that allows secure execution of pre-approved commands, enabling AI assistants to safely interact with the user's system.Last updated -1221
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -331
- -securityFlicense-qualityA Model Context Protocol server that allows AI assistants to interact with Prefect's workflow automation platform through natural language, enabling users to manage flows, deployments, tasks, and other Prefect resources via conversational commands.Last updated -4615