@ritsl-quotes/mcp-server

A lightweight CLI launcher for the Bexio MCP server with monetization support.

Installation

# Install globally
npm install -g @ritsl-quotes/mcp-server

# Or run directly with npx
npx -y @ritsl-quotes/mcp-server API_KEY="your-api-key"

Usage

The CLI launcher requires an API key, which you can obtain from your account dashboard at ritsl-quotes.com.

Basic Usage

# Run with your API key
npx -y @ritsl-quotes/mcp-server API_KEY="your-api-key"

Custom Port

By default, the server will run on port 3000. If this port is already in use, it will automatically select an available port. You can specify a custom port:

npx -y @ritsl-quotes/mcp-server API_KEY="your-api-key" PORT=3030

Custom Backend URL

For advanced users or testing, you can specify a custom backend URL:

npx -y @ritsl-quotes/mcp-server API_KEY="your-api-key" BACKEND_URL="https://api.staging.ritsl-quotes.com"

Development and Testing

Local Testing

For development and testing purposes without a production backend:

1. Start a local backend server:

   # In packages/backend directory
   npm run dev

2. In a separate terminal, run the CLI with the local backend URL:

   npx -y @ritsl-quotes/mcp-server API_KEY="test-key" BACKEND_URL="http://localhost:4000"

3. For local development on the CLI itself:

   # Make your changes
   npm run build
   # Install globally for testing
   sudo npm link
   # Test the locally linked package
   @ritsl-quotes/mcp-server API_KEY="test-key"

Configuring Claude Desktop

After installing the MCP server, you need to configure Claude Desktop to use it. Add the following to your Claude Desktop configuration file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": [
        "-y",
        "@ritsl-quotes/mcp-server",
        "--mcp-mode",
        "API_KEY=your-api-key"
      ]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "bexio": {
      "command": "npx",
      "args": [
        "-y",
        "@ritsl-quotes/mcp-server",
        "--mcp-mode",
        "API_KEY=your-api-key"
      ]
    }
  }
}

Important Notes About Claude Desktop Integration

When using the --mcp-mode flag, the MCP server operates in a special mode that communicates directly with Claude Desktop using the JSON-RPC protocol. This mode:

1. Handles all communication through stdin/stdout in proper JSON-RPC format
2. Formats log messages as valid JSON-RPC objects
3. Supports the Model Context Protocol (MCP) standard

If you encounter any issues with Claude Desktop integration:

1. Make sure you've included the --mcp-mode flag in your configuration
2. Restart Claude Desktop after making configuration changes
3. Check Claude Desktop logs for any errors

Troubleshooting

• API Key Issues: Make sure your API key is valid and has not expired.
• Port Conflicts: If you see errors about the port being in use, try specifying a different port or let the server find an available one automatically.
• Connection Issues: Check your internet connection and make sure you can reach the backend server.
• Debug Mode: To see more detailed logs, run with the DEBUG environment variable:

  DEBUG=1 npx -y @ritsl-quotes/mcp-server API_KEY="your-api-key"

Support

For support, contact [email protected] or visit our help center at help.ritsl-quotes.com.

License

© ritsl-quotes. All rights reserved.