MCPProxyServer

Intermediate proxy server for the minecraft protocol

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio coffeecoder1015-mcpproxyserver node server.js \
  --env PORT="Port to run the proxy on (e.g., 25565)" \
  --env LOG_LEVEL="debug|info|warn|error" \
  --env UPSTREAM_HOST="Hostname or IP of the actual Minecraft server to connect to" \
  --env UPSTREAM_PORT="Port of the actual Minecraft server"

How to use

MCPProxyServer is an intermediate proxy for the Minecraft protocol. It sits between a Minecraft client and an upstream Minecraft server, allowing you to observe, filter, or modify traffic as it passes through. To use it, start the proxy and configure your Minecraft client to connect to the proxy's listening address and port. The proxy will then forward traffic to the designated upstream server and relay responses back to the client. Depending on its capabilities, you may be able to enable logging, traffic inspection, or simple protocol-level transformations via the provided configuration and environment variables. If you need to inspect or debug traffic, enable a verbose log level and connect a test client to verify the proxy's behavior before deploying in production.

How to install

Prerequisites:

Node.js (≥ 14) and npm installed on your system

Installation steps:

Clone the repository: git clone https://github.com/coffeecoder1015-mcpproxyserver.git cd coffeecoder1015-mcpproxyserver
Install dependencies: npm install
Configure the proxy: create or edit a configuration file or use environment variables as described in the README. For example, you can set the port and upstream server details via environment variables described in the mcp_config section.
Start the proxy: npm start or node server.js
Verify the proxy is listening on the configured port and that a client can connect through to the upstream Minecraft server.

Additional notes

Tips and common considerations:

Ensure the proxy port (PORT) is accessible from the client and not blocked by firewalls.
Set UPSTREAM_HOST and UPSTREAM_PORT to the actual Minecraft server you want to proxy to.
Use LOG_LEVEL to control log verbosity; start with info or debug when troubleshooting.
If you modify protocol handling, test with a few clients and standard server builds to ensure compatibility.
Regularly update dependencies and monitor for security advisories related to Minecraft protocol handling.
If you encounter connection issues, verify network routing between the client, proxy, and upstream server, and check logs for handshake or encoding errors.