Issuebage MCP Server

- Validate an API key— Check whether an IssueBadge API key is valid usingvalidate_key.
- List all badges— Retrieve available badge templates for your organization withget_all_badges, optionally limiting the count.
- Create a badge template— Define a new badge with a name, description, and custom fields viacreate_badge.
- Issue a badge to a recipient— Award an existing badge to a person by name and email, with optional metadata, usingissue_badge.

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.

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

- Node.js 18+
- npm 8+
- IssueBadge API account with API key

git clone https://github.com/issuebadge/mcp-server.git cd mcp-server

cp .env.example .env # Edit .env with your IssueBadge API credentials

Create a.envfile based on.env.example:

# API Configuration ISSUEBADGE_BASE_URL=https://app.issuebadge.com/api/v1 ISSUEBADGE_API_KEY= # OAuth2 Configuration (Alternative) ISSUEBADGE_OAUTH_URL=https://app.issuebadge.com/api/v1/oauth ISSUEBADGE_OAUTH_TOKEN=your_oauth_token_here # Authentication Method (sanctum or oauth2) AUTH_METHOD=sanctum # Server Configuration MCP_SERVER_NAME=IssueBadge MCP Server MCP_SERVER_VERSION=1.0.0 # Optional Settings REQUEST_TIMEOUT=30000 DEBUG=false MAX_RETRIES=3 RETRY_DELAY=1000

Add this server to your Claude Desktop configuration:

{ "mcpServers": { "issuebadge": { "command": "node", "args": ["/absolute/path/to/mcp-server/dist/index.js"], "env": { "ISSUEBADGE_BASE_URL": "https://app.issuebadge.com /api/v1", "ISSUEBADGE_API_KEY": "", "AUTH_METHOD": "sanctum" } } } }

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

Validates IssueBadge API keys for authentication.

- api_key(string, required): The API key to validate

"Validate my API key: 1|abcdef123456789..."

Retrieves all available badges for the authenticated organization.

- limit(number, optional): Maximum badges to return (default: 100)

"Show me all available badges" "List the first 50 badges"

Creates a new badge template with optional custom fields.

- name(string, required): Badge name
- description(string, required): Badge description
- issuing_organization_name(string, required): Organization name
- idempotency_key(string, required): Unique identifier
- custom_fields(array, optional): Custom field definitions
- And more optional parameters...

"Create a badge called 'Web Development Certificate' for completing our full-stack course" "Create a Python certification badge with custom fields for completion date and final score"

Issues a badge to a recipient with optional metadata.

- badge_id(string, required): Badge ID from creation
- name(string, required): Recipient's full name
- idempotency_key(string, required): Unique identifier
- email(string, optional): Recipient's email
- metadata(object, optional): Custom field values

"Issue the Web Development badge to John Doe with email john@example.com" "Issue Python certification to Alice with completion date today and score 95%"

Human: "Create a badge for JavaScript mastery with fields for completion date and project count" AI: I'll create a JavaScript mastery badge with the custom fields you specified. ✨ Badge Created Successfully! 🏷️ Badge Name: JavaScript Mastery Certificate 🆔 Badge ID: js_mastery_2024_001 📋 Custom fields: completion_date (date), project_count (number)

Human: "Issue the JavaScript badge to Sarah Chen with completion date December 1st and 5 projects completed" AI: I'll issue the JavaScript mastery badge to Sarah Chen with the specified details. 🎉 Badge Issued Successfully! 📧 Recipient: Sarah Chen 🔗 Verification URL: https://yourdomain.com/verify/xyz123 📅 Completion Date: 2024-12-01 📊 Projects: 5

Human: "Create completion badges for all students in my Python course who scored above 85%" AI: I'll help you create and issue completion badges for high-performing students. First, let me create a Python Course Completion badge, then we can issue it to qualified students. [Creates badge and processes student list]

# Clone the repository git clone https://github.com/issuebadge/mcp-server.git cd mcp-server # Install dependencies npm install # Build TypeScript npm run build # Run in development mode npm run dev # Lint code npm run lint # Format code npm run format

mcp-server/ ├── src/ │ └── index.ts # Main MCP server implementation ├── dist/ # Compiled JavaScript (generated) ├── .env.example # Environment configuration template ├── package.json # Node.js dependencies and scripts ├── tsconfig.json # TypeScript configuration └── README.md # This file

- 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

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

- 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

- 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

- 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

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

- Follow TypeScript best practices
- Add comprehensive error handling
- Include JSDoc comments for functions
- Update tests for new features
- Follow semantic versioning

This project is licensed under the MIT License - see theLICENSEfile for details.

- 📖 Documentation: Check this README and inline code comments
- 🐛 Bug Reports:Open an issue
- 💬 Discussions:GitHub Discussions
- 📧 Email:support@issuebadge.com

# Check API key format (should start with number|) # Verify the key hasn't expired # Ensure correct base URL

# Check network connectivity # Verify IssueBadge service status # Increase REQUEST_TIMEOUT in .env

# Verify required fields are provided # Check idempotency key uniqueness # Validate organization permissions

- IssueBadge API: Core badge management platform
- Model Context Protocol: MCP specification and tools
- Claude Desktop: AI assistant with MCP support

An MCP server that integrates DottedSign capabilities with chat platforms and AI hosts such as ChatGPT and Claude to automate eSignature tasks like creating tasks, sending invites, and tracking signing workflow through simple natural language.