MCP Kit Local Relay

MCP Kit Local Relay

This command-line tool acts as a bridge, allowing local MCP clients that use standard input/output (stdio), like Claude Desktop, to interact with remote MCP Servers you've configured using the MCP Kit Web App.

It proxies requests to one target server at a time, making its tools and resources available locally.

Getting Started (Claude Desktop Example)

Follow these steps to connect Claude Desktop to your remote MCP Server using this relay:

Prerequisites:

• Node.js (v18 or later recommended)
• Node.js
• Git

Steps:

1. Clone the Relay: If you haven't already, clone this repository and navigate into the directory:

   git clone https://github.com/trevoruptain/mcp-local-relay
   cd local-relay
   

2. Install Dependencies:

   npm install
   

3. Configure the Relay: Create two configuration files directly inside the local-relay folder:

   • .env file: Create this file and add your MCP Kit API Key. You can generate an API key here.

     # Get your API Key from the MCP Kit Web App (app.mcpkit.ai) -> API Keys
     MCPKIT_API_KEY=your_api_key_here
     

     (Replace your_api_key_here with your actual key)

   • mcpconfig.json file: Create this file and specify the unique ID of the single remote MCP Server you want this relay to connect to.

     {
       "targetServerId": "your_target_server_id_here"
     }
     

     (Replace your_target_server_id_here with the Server ID found on the MCP Kit Web App -> Servers page)

4. Build the Relay: Compile the code:

   npm run build
   

   This creates a dist directory with the necessary JavaScript files. The main script is dist/index.js.

5. Configure Claude Desktop: You need to tell Claude Desktop how to run the relay script.

   • Open Claude Desktop settings (Menu -> Settings... -> Developer -> Edit Config).
   • Edit the claude_desktop_config.json file.
   • Add an entry under mcpServers. Use node as the command and provide the full, absolute path to the dist/index.js file you just built in the args.

   {
     "mcpServers": {
       "my_mcp_server": {
         // Choose a name for Claude Desktop to display
         "command": "node",
         "args": [
           // Replace this with the *absolute* path!
           "/Users/yourname/path/to/local-relay/dist/index.js"
         ]
       }
     }
   }
   

   • Important: Replace the example path with the actual absolute path on your system.
   • For detailed instructions on editing the Claude config, see the Local Relay Documentation. (Note: Update this link if the final URL is different)

6. Restart Claude Desktop: Quit and restart the Claude Desktop application completely.

7. Verify: Click the hammer icon

   

   MCP Hammer Icon

   in Claude Desktop's chat input. You should see the tools from your target server listed under the name you chose (e.g., my_mcp_server).

You can now use your remote MCP server's tools directly within Claude Desktop!

Running the Relay Manually

You can also run the relay directly from your terminal (e.g., for testing or use with other stdio clients):

npm start

This command executes node --stack-size=32768 dist/index.js. The relay will start listening for MCP commands on standard input. The --stack-size flag is included to prevent potential "Maximum call stack size exceeded" errors when dealing with large resources (like images).

Troubleshooting

• Claude Desktop Issues:
  • Hammer icon missing or tools not listed?
  • Double-check the absolute path to dist/index.js in claude_desktop_config.json.
  • Verify npm run build completed without errors.
  • Ensure .env and mcpconfig.json exist in the local-relay directory and contain the correct API key and Server ID.
  • Check Claude Desktop's own logs (see official MCP docs for locations).
• Relay Errors:
  • Check the local-relay-debug.log file created in the local-relay directory for detailed error messages from the relay itself.
  • Ensure your MCP_SERVER_URL in .env (or the default http://localhost:3002) points to a running instance of the mcp-kit-server.
  • Confirm your MCPKIT_API_KEY is valid.

Development

To run the relay in development mode with automatic restarts on code changes:

npm run dev

This uses nodemon and ts-node.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

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