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
- Install dependencies
- Configure environment
- Build the project
- Test the server
⚙️ 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 definitions- And 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
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 -2Python
- 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 -1318JavaScript
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to interact with n8n workflows through natural language, supporting actions like listing, creating, updating, executing and monitoring workflows.Last updated -411620TypeScriptMIT License
- -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 -16TypeScript