Remote-MCP
A type-safe, bidirectional system for remote Model Context Protocol communication.
Key Features
Use Cases
README
Remote-MCP: Remote Model Context Protocol
A type-safe, bidirectional and simple solution for remote MCP communication, allowing remote access and centralized management of model contexts.
Architecture
%%{init: {"flowchart": {"htmlLabels": false}} }%%
graph TD
%% Modern, Bright Color Styling with white text
classDef client fill:#22c55e,stroke:#059669,stroke-width:2px,color:#ffffff
classDef gateway fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff
classDef backend fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#ffffff
classDef resource fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#ffffff
classDef server fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#ffffff
linkStyle default stroke:#64748b,stroke-width:1.5px,stroke-dasharray: 5 5
%% Current MCP Setup (Multiple Local Servers)
subgraph Current["Current Setup (Local)"]
direction LR
subgraph ClientGroup["Client"]
A[Client]:::client
end
subgraph Servers["Local MCP Servers"]
direction TB
B1["Local MCP Server (DB)"]:::server -->|"DB Access"| C1[DB]:::resource
B2["Local MCP Server (API 1)"]:::server -->|"API Access"| C2["Web API 1"]:::resource
B3["Local MCP Server (API 2)"]:::server -->|"API Access"| C3["Web API 2"]:::resource
end
A -->|"MCP Protocol"| B1
A -->|"MCP Protocol"| B2
A -->|"MCP Protocol"| B3
end
%% Vertical separator
Current --> Proposed
%% Proposed MCP Architecture (Decoupled)
subgraph Proposed["Proposed Architecture (Remote)"]
direction LR
D[Client/Host]:::client -->|"MCP Protocol"| E["Local MCP Server (@remote-mcp/client)"]:::server
E <-->|"tRPC(HTTP)"| F["Remote MCP Server (@remote-mcp/server)"]:::backend
%% Separated Resources
F -->|"DB Access"| G1[DB]:::resource
F -->|"API Access"| G2["Web API 1"]:::resource
F -->|"API Access"| G3["Web API 2"]:::resource
end
Why I Made This (Now)
Yes, I know that the official MCP roadmap includes remote MCP support in the first quarter of 2025. However, the need for remote access was immediate for me, and likely for many others. This library was created to bridge that gap, providing a way to connect to a remote MCP server from a local MCP client right now, without waiting for future official implementations.
Note: I don't want this to be a sophisticated or overcomplicated thing. This way just works right now.
Getting Started
Note: This project is currently under active development and is considered experimental. Expect breaking changes and potential issues.
Client Usage
Use Publicly Published Package
Just put the following code in your MCP client settings, in here I'm using Claude as an example:
{
"mcpServers": {
"remote-mcp": {
"command": "npx",
"args": ["-y", "@remote-mcp/client"],
"env": {
"REMOTE_MCP_URL": "http://localhost:9512",
"HTTP_HEADER_Authorization": "Bearer <token>"
}
}
}
}
Code Your Own Local MCP Server
Install requirements:
$ npm install @remote-mcp/client @trpc/client@next zod
then write your own code like the following:
import { RemoteMCPClient } from "@remote-mcp/client";
const client = new RemoteMCPClient({
remoteUrl: "http://localhost:9512",
onError: (method, error) => console.error(`Error in ${method}:`, error)
});
void client.start();
Server Usage (Remote MCP Implementation)
You can see some examples in the examples directory.
Code Your Own Remote MCP Server
After npm install @remote-mcp/server, you can your own remote MCP server like the following:
import { MCPRouter, LogLevel } from "@remote-mcp/server";
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { z } from "zod";
// Create router instance
const mcpRouter = new MCPRouter({
logLevel: LogLevel.DEBUG,
name: "example-server",
version: "1.0.0",
capabilities: {
logging: {},
},
});
// Add example tool
mcpRouter.addTool(
"calculator",
{
description:
"Perform basic calculations. Add, subtract, multiply, divide. Invoke this every time you need to perform a calculation.",
schema: z.object({
operation: z.enum(["add", "subtract", "multiply", "divide"]),
a: z.string(),
b: z.string(),
}),
},
async (args) => {
const a = Number(args.a);
const b = Number(args.b);
let result: number;
switch (args.operation) {
case "add":
result = Number(a) + b;
break;
case "subtract":
result = a - b;
break;
case "multiply":
result = a * b;
break;
case "divide":
if (b === 0) throw new Error("Division by zero");
result = a / b;
break;
}
return {
content: [{ type: "text", text: `${result}` }],
};
},
);
const appRouter = mcpRouter.createTRPCRouter();
void createHTTPServer({
router: appRouter,
createContext: () => ({}),
}).listen(Number(process.env.PORT || 9512));
Then you can see like the following in your MCP client:
Packages
This repository contains:
@remote-mcp/client: Client library acting as a local MCP server, connecting to a remote implementation.@remote-mcp/server: Server library for creating remotely accessible MCP services (used as the remote implementation).
Roadmap
Core Features
- Basic Type-safe Client/Server Communication
- Basic MCP Command Support
- Basic MCP Tool Support
- Basic MCP Prompt Support
- Crash-Safe Handling (WIP, top priority)
- Complete Event Subscription System
- Resource change notifications
- Tool/Prompt list change notifications
- HTTP Header Support
- Custom Headers
- Authentication Middleware
- Basic error handling improvements
- Basic middleware support
Framework Support
- Nest.js Integration (
@remote-mcp/nestjs)
Advanced Features
- Bidirectional communication
- Server-to-client requests
- Resource sharing between server/client
- Basic monitoring & logging
Contribute
Contributions are welcome. See CONTRIBUTING.md for details.
Disclaimer
This library is a complementary extension, not part of the official MCP specification, built upon existing MCP concepts.
License
This project is licensed under the MIT License. See the LICENSE file for details.
References
Star History
Repository Owner
User
Repository Details
Programming Languages
Tags
Topics
Join Our Newsletter
Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.
Related MCPs
Discover similar Model Context Protocol servers
Weblate MCP Server
Seamlessly connect AI assistants to Weblate for translation management via the Model Context Protocol.
Weblate MCP Server enables AI assistants and clients to directly manage Weblate translation projects through the Model Context Protocol (MCP). It integrates with the Weblate REST API, allowing natural language interaction for project and translation management. The tool offers multiple transport options including HTTP, SSE, and STDIO, and is optimized for large language model workflows. Full support for project, component, and translation operations is provided, with a focus on type safety and flexible environment configuration.
- ⭐ 9
- MCP
- mmntm/weblate-mcp
Godot MCP
A Model Context Protocol (MCP) server implementation using Godot and Node.js.
Godot MCP implements the Model Context Protocol (MCP) as a server, leveraging the Godot game engine along with Node.js and TypeScript technologies. Designed for seamless integration and efficient context management, it aims to facilitate standardized communication between AI models and applications. This project offers a ready-to-use MCP server for developers utilizing Godot and modern JavaScript stacks.
- ⭐ 1,071
- MCP
- Coding-Solo/godot-mcp
GameBrain MCP API Clients
Easily connect to the GameBrain MCP server with customizable client configuration.
GameBrain MCP API Clients enables users to seamlessly integrate with the GameBrain Model Context Protocol (MCP) server by providing a ready-to-use configuration and client setup. Users can generate a free API key and connect to the server with minimal setup using the supplied JSON config. The tool is designed to facilitate standardized access and communication with remote model context providers.
- ⭐ 2
- MCP
- ddsky/gamebrain-api-clients
Teamwork MCP Server
Seamless Teamwork.com integration for Large Language Models via the Model Context Protocol
Teamwork MCP Server is an implementation of the Model Context Protocol (MCP) that enables Large Language Models to interact securely and programmatically with Teamwork.com. It offers standardized interfaces, including HTTP and STDIO, allowing AI agents to perform various project management operations. The server supports multiple authentication methods, an extensible toolset architecture, and is designed for production deployments. It provides read-only capability for safe integrations and robust observability features.
- ⭐ 11
- MCP
- Teamwork/mcp
Stape MCP Server
An MCP server implementation for integrating Stape with AI model context protocols.
Stape MCP Server provides an implementation of the Model Context Protocol server tailored for the Stape platform. It enables secure and standardized access to model context capabilities, allowing integration with tools such as Claude Desktop and Cursor AI. Users can easily configure and authenticate MCP connections using provided configuration samples, while managing context and credentials securely. The server is open source and maintained by the Stape Team under the Apache 2.0 license.
- ⭐ 4
- MCP
- stape-io/stape-mcp-server
MCP Server for Google Tag Manager
Remote MCP server enabling Google Tag Manager integration with AI clients.
MCP Server for Google Tag Manager enables remote MCP connections with built-in Google OAuth, creating an interface to the Google Tag Manager API. It facilitates secure authentication and streamlined access for AI tools like Claude Desktop and Cursor AI. Developers can quickly configure their MCP clients for seamless integration and manage credentials with ease. Tools and workflows become accessible once authenticated, enhancing contextual interaction and automation through Google Tag Manager.
- ⭐ 70
- MCP
- stape-io/google-tag-manager-mcp-server
Didn't find tool you were looking for?