{"id":27235062,"url":"https://github.com/EvalsOne/MCP-connect","last_synced_at":"2025-04-10T16:03:12.178Z","repository":{"id":269121427,"uuid":"906489734","full_name":"EvalsOne/MCP-connect","owner":"EvalsOne","description":"Enables cloud-based AI services to access local Stdio based MCP servers","archived":false,"fork":false,"pushed_at":"2025-01-07T13:39:54.000Z","size":164,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-07T14:31:57.350Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvalsOne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-21T03:45:33.000Z","updated_at":"2025-01-07T13:40:22.000Z","dependencies_parsed_at":"2024-12-21T05:17:19.387Z","dependency_job_id":"108e3562-86b7-4b3c-beaf-a51c1f26d753","html_url":"https://github.com/EvalsOne/MCP-connect","commit_stats":null,"previous_names":["evalsone/mcp-bridge","evalsone/mcp-connect"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvalsOne%2FMCP-connect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvalsOne%2FMCP-connect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvalsOne%2FMCP-connect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvalsOne%2FMCP-connect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvalsOne","download_url":"https://codeload.github.com/EvalsOne/MCP-connect/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248249420,"owners_count":21072359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-10T16:01:55.161Z","updated_at":"2025-04-10T16:03:12.173Z","avatar_url":"https://github.com/EvalsOne.png","language":"TypeScript","funding_links":[],"categories":["MCP Clients","Gateways \u0026 Proxies","Python","📚 Projects (1974 total)"],"sub_categories":["Weather","MCP Servers"],"readme":"# MCP Connect\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n    ███╗   ███╗ ██████╗██████╗      ██████╗ ██████╗ ███╗   ██╗███╗   ██╗███████╗ ██████╗████████╗\n    ████╗ ████║██╔════╝██╔══██╗    ██╔════╝██╔═══██╗████╗  ██║████╗  ██║██╔════╝██╔════╝╚══██╔══╝\n    ██╔████╔██║██║     ██████╔╝    ██║     ██║   ██║██╔██╗ ██║██╔██╗ ██║█████╗  ██║        ██║   \n    ██║╚██╔╝██║██║     ██╔═══╝     ██║     ██║   ██║██║╚██╗██║██║╚██╗██║██╔══╝  ██║        ██║   \n    ██║ ╚═╝ ██║╚██████╗██║         ╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗   ██║   \n    ╚═╝     ╚═╝ ╚═════╝╚═╝          ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚══════╝ ╚═════╝   ╚═╝   \n\nThe Model Context Protocol (MCP) introduced by Anthropic is cool. However, most MCP servers are built on Stdio transport, which, while excellent for accessing local resources, limits their use in cloud-based applications.\n\nMCP Connect is a tiny tool that is created to solve this problem:\n\n- **Cloud Integration**: Enables cloud-based AI services to interact with local Stdio based MCP servers\n- **Protocol Translation**: Converts HTTP/HTTPS requests to Stdio communication\n- **Security**: Provides secure access to local resources while maintaining control\n- **Flexibility**: Supports various MCP servers without modifying their implementation\n- **Easy to use**: Just run MCP Connect locally, zero modification to the MCP server\n- **Tunnel**: Built-in support for Ngrok tunnel\n\nBy bridging this gap, we can leverage the full potential of local MCP tools in cloud-based AI applications without compromising on security.\n\n## How it works\n\n```\n+-----------------+     HTTPS/SSE      +------------------+      stdio      +------------------+\n|                 |                    |                  |                 |                  |\n|  Cloud AI tools | \u003c---------------\u003e  |  Node.js Bridge  | \u003c------------\u003e  |    MCP Server    |\n|   (Remote)      |       Tunnels      |    (Local)       |                 |     (Local)      |\n|                 |                    |                  |                 |                  |\n+-----------------+                    +------------------+                 +------------------+\n```\n\n## Prerequisites\n\n- Node.js\n\n## Quick Start\n\n1. Clone the repository\n   ```bash\n   git clone https://github.com/EvalsOne/MCP-connect.git\n   ```\n   and enter the directory\n   ```bash\n   cd MCP-connect\n   ```\n2. Copy `.env.example` to `.env` and configure the port and auth_token:\n   ```bash\n   cp .env.example .env\n   ```\n3. Install dependencies:\n   ```bash\n   npm install\n   ```\n4. Run MCP Connect\n   ```bash\n   # build MCP Connect\n   npm run build\n   # run MCP Connect\n   npm run start\n   # or, run in dev mode (supports hot reloading by nodemon)\n   npm run dev\n   ```\nNow MCP connect should be running on `http://localhost:3000/bridge`.\n\nNote:\n- The bridge is designed to be run on a local machine, so you still need to build a tunnel to the local MCP server that is accessible from the cloud.\n- Ngrok, Cloudflare Zero Trust, and LocalTunnel are recommended for building the tunnel.\n\n## Running with Ngrok Tunnel\n\nMCP Connect has built-in support for Ngrok tunnel. To run the bridge with a public URL using Ngrok:\n\n1. Get your Ngrok auth token from https://dashboard.ngrok.com/authtokens\n2. Add to your .env file:\n   ```\n   NGROK_AUTH_TOKEN=your_ngrok_auth_token\n   ```\n3. Run with tunnel:\n   ```bash\n   # Production mode with tunnel\n   npm run start:tunnel\n   \n   # Development mode with tunnel\n   npm run dev:tunnel\n   ``` \nAfter MCP Connect is running, you can see the MCP bridge URL in the console.\n\n## API Endpoints\n\nAfter MCP Connect is running, there are two endpoints exposed:\n\n- `GET /health`: Health check endpoint\n- `POST /bridge`: Main bridge endpoint for receiving requests from the cloud\n\nFor example, the following is a configuration of the official [GitHub MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/github):\n\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\n    \"-y\",\n    \"@modelcontextprotocol/server-github\"\n  ],\n  \"env\": {\n    \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003cyour_github_personal_access_token\u003e\"\n  }\n}\n```\n\nYou can send a request to the bridge as the following to list the tools of the MCP server and call a specific tool.\n\n**Listing tools:**\n\n```bash\ncurl -X POST http://localhost:3000/bridge \\\n     -d '{\n       \"method\": \"tools/list\",\n       \"serverPath\": \"npx\",\n       \"args\": [\n         \"-y\",\n         \"@modelcontextprotocol/server-github\"\n       ],\n       \"params\": {},\n       \"env\": {\n         \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003cyour_github_personal_access_token\u003e\"\n       }\n     }'\n```\n\n**Calling a tool:**\n\nUsing the search_repositories tool to search for repositories related to modelcontextprotocol\n\n```bash\ncurl -X POST http://localhost:3000/bridge \\\n     -d '{\n       \"method\": \"tools/call\",\n       \"serverPath\": \"npx\",\n       \"args\": [\n         \"-y\",\n         \"@modelcontextprotocol/server-github\"\n       ],\n       \"params\": {\n         \"name\": \"search_repositories\",\n         \"arguments\": {\n            \"query\": \"modelcontextprotocol\"\n         },\n       },\n       \"env\": {\n         \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003cyour_github_personal_access_token\u003e\"\n       }\n     }'\n```\n\n## Authentication\n\nMCP Connect uses a simple token-based authentication system. The token is stored in the `.env` file. If the token is set, MCP Connect will use it to authenticate the request.\n\nSample request with token:\n\n```bash\ncurl -X POST http://localhost:3000/bridge \\\n     -H \"Authorization: Bearer \u003cyour_auth_token\u003e\" \\\n     -d '{\n       \"method\": \"tools/list\",\n       \"serverPath\": \"npx\",\n       \"args\": [\n         \"-y\",\n         \"@modelcontextprotocol/server-github\"\n       ],\n       \"params\": {},\n       \"env\": {\n         \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"\u003cyour_github_personal_access_token\u003e\"\n       }\n     }'\n```\n\n## Configuration\n\nRequired environment variables:\n\n- `AUTH_TOKEN`: Authentication token for the bridge API (Optional)\n- `PORT`: HTTP server port (default: 3000, required)\n- `LOG_LEVEL`: Logging level (default: info, required)\n- `NGROK_AUTH_TOKEN`: Ngrok auth token (Optional)\n\n## Using MCP Connect with ConsoleX AI to access local MCP Server\n\nThe following is a demo of using MCP Connect to access a local MCP Server on [ConsoleX AI](https://consolex.ai):\n\n[![MCP Connect Live Demo](readme/thumbnail.png)](https://github-production-user-asset-6210df.s3.amazonaws.com/6077178/400736575-19dec583-7911-4221-bd87-3e6032ea7732.mp4)\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvalsOne%2FMCP-connect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEvalsOne%2FMCP-connect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvalsOne%2FMCP-connect/lists"}