tumiki-proxy is a transparent MCP traffic logging proxy for Claude Code and backend MCP servers. It records all MCP traffic to local NDJSON-formatted logs, supporting multiple transports (stdio, HTTP/StreamableHTTP, and HTTP/SSE) and providing optional authentication for HTTP-based servers. The proxy acts as a zero-impact wrapper that does not modify MCP protocol messages, enabling efficient asynchronous buffering and batched writes for debugging and analysis. You can run separate configured instances for local stdio usage (e.g., filesystem logging) or remote MCP servers (e.g., Context7) via HTTP/StreamableHTTP or SSE transports. To use, configure mcpServers in a .mcp.json file or pass equivalent command-line options, set the required environment variables (such as the log file path and API keys), and start the proxy to begin logging traffic between Claude Code and your MCP backend.

Prerequisites:

• A supported runtime (Bun + binary or Node.js environment) or a prebuilt binary for your platform.
• Basic shell access to install/run commands.

Installation steps (recommended paths):

1. Install via Homebrew (macOS/Linux) if you prefer a package manager:

   • brew tap rayven122/tumiki-proxy https://github.com/rayven122/tumiki-proxy
   • brew install tumiki-proxy
   • brew update && brew upgrade tumiki-proxy
   • See the Homebrew install guide for details.

2. Download a prebuilt binary from releases (example for macOS/Linux/Windows):

   • curl -L -o tumiki-proxy https://github.com/rayven122/tumiki-proxy/releases/latest/download/tumiki-proxy-linux-x64
   • chmod +x tumiki-proxy

   • or appropriate binary for your platform

3. Build from source (recommended for development):

   • git clone https://github.com/rayven122/tumiki-proxy.git
   • cd tumiki-proxy
   • Bun-based build (recommended): bun install bun run build bun run build:binary

     Generates a standalone tumiki-proxy binary

   • Node.js-based build (alternative): npm install npm run build

     Run via Node.js: node dist/index.js [args...]

4. Run the proxy with a sample configuration:

   • Create a .mcp.json in the project root or run inline with command-line options as shown in the README.
   • Example (stdio mode for local MCP server): export TUMIKI_LOG_FILE="./mcp-filesystem.log" ./tumiki-proxy npx -y @modelcontextprotocol/server-filesystem /path/to/dir

Prerequisites recap:

• A runtime compatible with the chosen distribution (Bun binary or Node.js 18+).
• Access to a shell to run the commands above.
• Adequate permissions for creating log files as specified by TUMIKI_LOG_FILE.

Tips and common issues:

• Ensure TUMIKI_LOG_FILE is set and writable; otherwise logs will not be created.
• For HTTP-based transports, supply proper API keys via CONTEXT7_API_KEY, MCP_API_KEY, or API_KEY depending on the server, and verify network access to the MCP backend.
• If StreamableHTTP fails, the proxy will automatically fall back to SSE transport; check logs for messages like 'StreamableHTTP connection failed, falling back to SSE transport'.
• If logs are not appearing, confirm the correct mcpServers configuration in .mcp.json (or the equivalent runtime flags) and verify that the command path to the tumiki-proxy binary is correct.
• The logs use NDJSON; you can grep or parse lines to analyze requests, responses, and transport events.
• When using the binary, provide a relative or absolute path to the executable in the command field of the config to ensure correct startup in different environments.