GLEC MCP Server

A Model Context Protocol (MCP) server that provides access to the GLEC API for calculating carbon emissions from logistics and transportation. This server enables Claude Desktop to interact with GLEC's emission calculation services through natural language.

🔑 Deployment Information

Repository Owner: [email protected]
GitHub Token: [REDACTED - See deployment guide]
Repository URL: https://github.com/gleccloud/glec-mcp-server
NPM Package: @glec/[email protected]
Smithery API Key: 79f45de2-1139-452c-aa2e-30e615314b4b

Manual GitHub Repository Creation

1. Go to https://github.com/new
2. Repository name: glec-mcp-server
3. Description: GLEC API MCP Server - Claude Desktop integration for global logistics carbon emission calculations
4. Set to Public
5. Do not initialize with README (already exists)
6. Create repository
7. Run: git push -u origin main

🌟 Features

• 🚛 Multi-Modal Transport: Calculate emissions for road, rail, air, and sea transport
• 📊 ESG Reporting: Generate comprehensive ESG and compliance reports
• 👥 Shipper Management: Manage shipper information and data
• 🔒 Enterprise Security: Encrypted API key storage and comprehensive logging
• ⚡ High Performance: Rate limiting, caching, and optimized API calls
• 🛡️ Error Handling: Robust error handling with detailed error messages
• 📈 Monitoring: Built-in logging and performance monitoring

🚀 Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• Claude Desktop (Windows)
• GLEC API Key (get from GLEC Console)

Installation

1. Install the MCP server globally:

   npm install -g @glec/mcp-server

2. Get your GLEC API Key:

   • Visit GLEC Console
   • Sign up or log in to your account
   • Navigate to API Keys section
   • Create a new API key
   • Copy the API key for configuration

3. Configure Claude Desktop:

   • Open Claude Desktop settings
   • Go to "MCP Servers" section
   • Add new server configuration
   • Use the configuration provided below

⚙️ Configuration

Claude Desktop Configuration

Add the following configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "glec-api": {
      "command": "glec-mcp",
      "env": {
        "GLEC_API_KEY": "your-glec-api-key-here",
        "GLEC_BEARER_TOKEN": "your-bearer-token-here",
        "GLEC_BASE_URL": "https://open-api.glec.io",
        "GLEC_TIMEOUT": "30000",
        "GLEC_RETRIES": "3",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GLEC_API_KEY | ✅ | - | Your GLEC API key from the console | | GLEC_BEARER_TOKEN | ❌ | - | Bearer token for advanced features | | GLEC_BASE_URL | ❌ | https://open-api.glec.io | GLEC API base URL | | GLEC_TIMEOUT | ❌ | 30000 | Request timeout in milliseconds | | GLEC_RETRIES | ❌ | 3 | Number of retry attempts | | LOG_LEVEL | ❌ | info | Logging level (debug, info, warn, error) |

🛠️ Available Tools

Emission Calculation

glec_calculate_road_emission

Calculate CO2 emissions for road transport.

Parameters:

• transportMode (required): Transport mode code (M001, M002, M003)
• distance (required): Distance in kilometers
• weight (required): Weight in tons
• startLocation (optional): Starting location
• endLocation (optional): Ending location
• transportDate (optional): Transport date (YYYY-MM-DD)
• distanceUnit (optional): Distance unit (km, miles)
• weightUnit (optional): Weight unit (t, kg, lbs)
• vehicleType (optional): Vehicle type
• fuelType (optional): Fuel type
• loadFactor (optional): Load factor (0-1)

Example:

{
  "transportMode": "M001",
  "distance": 100,
  "weight": 5,
  "startLocation": "Seoul",
  "endLocation": "Busan",
  "transportDate": "2024-01-15"
}

glec_calculate_rail_emission

Calculate CO2 emissions for rail transport.

Parameters:

• transportMode (required): Rail transport mode code (R001, R002, R003)
• distance (required): Distance in kilometers
• weight (required): Weight in tons
• trainType (optional): Train type
• electrification (optional): Electrification type

glec_calculate_air_emission

Calculate CO2 emissions for air transport.

Parameters:

• transportMode (required): Air transport mode code (A001, A002, A003)
• distance (required): Distance in kilometers
• weight (required): Weight in tons
• aircraftType (optional): Aircraft type
• flightType (optional): Flight type (domestic, international)

glec_calculate_sea_emission

Calculate CO2 emissions for sea transport.

Parameters:

• transportMode (required): Sea transport mode code (S001, S002, S003)
• distance (required): Distance in kilometers
• weight (required): Weight in tons
• shipType (optional): Ship type
• containerType (optional): Container type

Shipper Management

glec_list_shippers

List all registered shippers.

Parameters:

• page (optional): Page number (default: 1)
• size (optional): Page size (default: 10)
• search (optional): Search term

glec_create_shipper

Create a new shipper.

Parameters:

• name (required): Shipper name
• email (optional): Shipper email
• phone (optional): Phone number
• address (optional): Address
• country (optional): Country code
• industry (optional): Industry type
• companySize (optional): Company size

Reports

glec_generate_esg_report

Generate ESG report.

Parameters:

• startDate (required): Start date (YYYY-MM-DD)
• endDate (required): End date (YYYY-MM-DD)
• format (optional): Report format (pdf, excel, json)
• scope (optional): Emission scope (1, 2, 3, 1,2, 1,3, 2,3, 1,2,3)
• language (optional): Report language (ko, en, ja, zh)
• includeCharts (optional): Include charts (default: true)
• includeDetails (optional): Include detailed data (default: true)
• certificationStandard (optional): Certification standard

Utilities

glec_get_emission_codes

Get emission factor codes.

Parameters:

• transportMode (required): Transport mode (road, rail, air, sea)
• category (required): Vehicle size category (small, medium, large)

glec_health_check

Check GLEC API health status.

📚 Usage Examples

Basic Emission Calculation

User: "Calculate the CO2 emissions for transporting 10 tons of goods 200km by road using a medium truck."

Claude: I'll calculate the road transport emissions for you.

Multi-Modal Comparison

User: "Compare the emissions for transporting 5 tons 500km by road vs rail."

Claude: I'll calculate emissions for both transport modes and compare them.

ESG Report Generation

User: "Generate an ESG report for Q1 2024 in PDF format."

Claude: I'll generate an ESG report for Q1 2024 in PDF format.

🔧 Development

Local Development

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Set environment variables:

   cp .env.example .env
   # Edit .env with your API key

4. Build the project:

   npm run build

5. Run in development mode:

   npm run dev

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Linting and Formatting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

🐛 Troubleshooting

Common Issues

1. Authentication Error

Error: Authentication Error: Authentication failed

Solution:

• Verify your API key is correct
• Check if the API key is active in GLEC Console
• Ensure the API key has the required permissions

2. Rate Limit Exceeded

Error: Rate Limit Error: Rate limit exceeded

Solution:

• Wait for the rate limit window to reset
• Consider upgrading your GLEC API plan
• Implement request batching for bulk operations

3. Network Connection Error

Error: Network Error: Network connection failed

Solution:

• Check your internet connection
• Verify the GLEC API is accessible
• Check firewall settings

4. Validation Error

Error: Validation Error: Invalid input parameters

Solution:

• Check parameter types and values
• Ensure required parameters are provided
• Verify parameter ranges and formats

Debug Mode

Enable debug logging to troubleshoot issues:

{
  "env": {
    "LOG_LEVEL": "debug"
  }
}

Logs

Logs are written to:

• Console output (for real-time debugging)
• logs/error.log (error logs)
• logs/combined.log (all logs)

📊 Performance

Rate Limits

• General API calls: 100 requests/minute
• Emission calculations: 50 requests/minute
• Report generation: 10 requests/5 minutes
• Shipper management: 20 requests/minute

Response Times

• Emission calculations: < 1 second
• Shipper operations: < 500ms
• Report generation: 5-30 seconds (depending on complexity)

Caching

The server implements intelligent caching for:

• Emission factor codes
• Shipper information
• API responses (with appropriate TTL)

🔒 Security

Data Protection

• API keys are encrypted at rest
• All API communications use HTTPS
• Sensitive data is redacted from logs
• Request/response data is sanitized

Authentication

• Supports both GlecApiKey and Bearer token authentication
• Automatic token rotation support
• Secure credential storage

Audit Logging

• All API calls are logged with correlation IDs
• Security events are tracked
• Audit trail for compliance

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

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

🆘 Support

• Documentation: https://glec.io/docs
• Issues: GitHub Issues
• Email: [email protected]
• Discord: GLEC Community

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• Anthropic for Claude Desktop
• GLEC for the emission calculation API

Made with ❤️ by the GLEC team