vshosting-mcp

MCP server for vshosting.cloud API - manage support tickets from any MCP-compatible LLM client

⚠️ Unofficial Community Project - This is a community-maintained MCP server and is not officially affiliated with or endorsed by vshosting.

Features

• 6 MCP Tools for complete ticket management
• Interactive Prompt (/vsh) for guided workflows
• Auto-authentication with automatic token refresh
• Comprehensive Zod schemas for type-safe API responses
• Czech language support for ticket communications
• Optimized responses - Minimal summaries to reduce token usage
• Single bundled file - No node_modules dependency required

Installation

Quick Start with npx

[email protected] \
VSHOSTING_PASSWORD=yourpassword \
VSHOSTING_CLIENT_ID=your-client-id \
npx vshosting-mcp

Global Installation

npm install -g vshosting-mcp
vshosting-mcp

Local Installation

npm install vshosting-mcp

Configuration

Required Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | VSHOSTING_EMAIL | Your vshosting account email | [email protected] | | VSHOSTING_PASSWORD | Your vshosting account password | your-password | | VSHOSTING_CLIENT_ID | Your client ID from vshosting | your-client-id-here |

Optional Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | VSHOSTING_API_URL | API base URL | https://admin.vshosting.cloud | | VSHOSTING_TIMEOUT | Request timeout in milliseconds | 30000 | | VSHOSTING_DEBUG | Enable debug logging | false | | VSHOSTING_LOG_LEVEL | Log level (DEBUG, INFO, WARN, ERROR) | INFO | | VSHOSTING_LOG_FILE | Custom log file path | logs/vshosting-mcp.log | | VSHOSTING_LOG_TO_FILE | Enable file logging | true |

Usage with Claude Code

Add to your Claude Code MCP server configuration:

{
  "mcpServers": {
    "vshosting": {
      "command": "npx",
      "args": ["-y", "vshosting-mcp"],
      "env": {
        "VSHOSTING_EMAIL": "[email protected]",
        "VSHOSTING_PASSWORD": "yourpassword",
        "VSHOSTING_CLIENT_ID": "your-client-id"
      }
    }
  }
}

Or with global installation:

{
  "mcpServers": {
    "vshosting": {
      "command": "vshosting-mcp",
      "env": {
        "VSHOSTING_EMAIL": "[email protected]",
        "VSHOSTING_PASSWORD": "yourpassword",
        "VSHOSTING_CLIENT_ID": "your-client-id"
      }
    }
  }
}

Available Tools

Ticket Management

• vshosting_list_tickets - List all support tickets (minimal summary format)

  • Optional: clientId - Client ID (uses default if not provided)
  • Returns: Minimal ticket list with id, code, title, status, lastUpdate, message count

• vshosting_get_ticket - Get detailed ticket information

  • Required: ticketId - Ticket ID
  • Returns: Full ticket details with all messages and attachments

• vshosting_create_ticket - Create new support ticket

  • Required: title, message, topicId
  • Optional: clientId, attachments
  • Returns: Created ticket details

• vshosting_reply_ticket - Reply to existing ticket

  • Required: ticketId, message
  • Optional: attachments
  • Returns: Updated ticket details

• vshosting_list_topics - Get available ticket categories

  • Optional: clientId
  • Returns: List of topics with Czech names, groups, and templates

User Information

• vshosting_get_user - Get current user and client information
  • Returns: User profile with associated clients and services

Interactive Prompt

/vsh - vshosting Support Assistant

Interactive guide for managing vshosting support tickets with intelligent workflow:

Usage:

/vshosting:vshosting Support (MCP)
/vshosting:vshosting Support (MCP) create
/vshosting:vshosting Support (MCP) view
/vshosting:vshosting Support (MCP) reply

Features:

• CREATE workflow:

  • Fetches ALL available ticket topics
  • Intelligently selects the most appropriate topic
  • Helps compose professional Czech messages
  • Shows preview for confirmation before creating

• VIEW workflow:

  • Lists all tickets or shows specific ticket details
  • Formatted display with status and timeline

• REPLY workflow:

  • Shows current ticket history
  • Helps compose Czech follow-up messages
  • Confirms before sending

How It Works

1. Auto-authentication - Server authenticates on startup using your credentials
2. Token Management - Automatic token refresh (tokens valid for 30 minutes)
3. Smart Client Selection - Uses configured VSHOSTING_CLIENT_ID or your primary client
4. Czech Language - All ticket messages composed in professional Czech
5. Error Handling - Comprehensive error logging to logs/vshosting-mcp.log

Example Workflows

Creating a Technical Support Ticket

User: /vshosting:vshosting Support (MCP) create
Claude: I'll help you create a ticket. What issue are you experiencing?
User: Need to upgrade Kubernetes cluster to v1.33
Claude: [Fetches topics, selects "Linux managed služby", composes Czech message]

        Selected Topic: Linux managed služby (TECHNICAL)

        Title: Žádost o upgrade Kubernetes clusteru na v1.33

        Message: [Full Czech text]

        Shall I create this ticket?
User: yes
Claude: [Creates ticket] ✓ Ticket 5QRZM created successfully

Viewing Tickets

User: /vshosting:vshosting Support (MCP) view
Claude: [Lists all tickets in summary format]
        - 8PUND: Navýšení úložiště (RESOLVED) - 3 messages
        - 5Z35R: PostgreSQL upgrade (CLOSED) - 19 messages
        ...

Architecture

• API Client (src/api/client.ts) - Full vshosting API implementation
• Token Manager (src/utils/auth.ts) - Handles authentication and refresh
• Zod Schemas (src/schemas/responses.ts) - Comprehensive type validation
• MCP Server (src/index.ts) - Tool and prompt registrations
• Logger (src/utils/logger.ts) - File and stderr logging

Development

# Clone repository
git clone https://github.com/asonnleitner/vshosting-mcp.git
cd vshosting-mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Development (watch mode)
pnpm dev

# Run locally
export [email protected]
export VSHOSTING_PASSWORD=yourpassword
export VSHOSTING_CLIENT_ID=your-client-id
node dist/index.mjs

# Lint
pnpm lint

# Type check
pnpm typecheck

Troubleshooting

Authentication Fails

Error: ✗ Authentication failed: API request failed: Bad Request

Solutions:

1. Verify your email and password are correct
2. Check that VSHOSTING_CLIENT_ID is valid
3. Enable debug logging: VSHOSTING_DEBUG=true VSHOSTING_LOG_LEVEL=DEBUG
4. Check logs: cat logs/vshosting-mcp.log

MCP Server Won't Connect in Claude Code

Solutions:

1. Verify the server starts manually: node dist/index.mjs (with env vars)
2. Check Claude Code MCP panel for connection errors
3. Rebuild: pnpm build
4. Restart Claude Code completely
5. Check the path in your MCP config is correct

Schema Validation Errors

If you encounter output validation errors, this usually means the API response structure changed. Please open an issue on GitHub.

Security

• Credentials: Stored only in environment variables, never logged or persisted
• Tokens: Kept in memory only, cleared on logout
• Logging: Credentials and tokens are never written to log files
• HTTPS: All API communication over HTTPS

⚠️ Best Practice: Use a secrets management tool or encrypted environment variables in production.

Contributing

Contributions are welcome! Please:

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

Changelog

See CHANGELOG.md for version history.

License

MIT © Andreas Sonnleitner

Acknowledgments

• Built for the Model Context Protocol
• Uses the official @modelcontextprotocol/sdk
• Designed for use with Claude Code and other MCP-compatible clients

Links

• GitHub Repository
• npm Package
• Report Issues
• vshosting.cloud (unofficial integration)
• Model Context Protocol