<div align="center">

# MCP Hub

**Connect your tools once. Use them everywhere.**

One self-hosted server that exposes Google Drive, your local files, the web and more to
Claude, ChatGPT, Cursor, Claude Code and any other [Model Context Protocol](https://modelcontextprotocol.io) client.

[![CI](https://github.com/mherub004/mcp-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/mherub004/mcp-hub/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-7c9cff.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D24-3ddc97.svg)](https://nodejs.org)

[SaaS quick start](#saas-quick-start) · [Self-hosted mode](#self-hosted-mode) · [SaaS guide](docs/saas.md) · [Connectors](docs/connectors.md)

</div>

---

## SaaS quick start

MCP Hub now has a customer-facing SaaS mode. People can create accounts, track public web pages
and selected Google Drive files, see change history, and issue separate MCP keys to their AI
clients. The hosted edition has Free and Pro usage limits; Stripe Checkout and the billing portal
activate when you supply your Stripe account keys and recurring Price ID. The self-hosted edition
remains available under the MIT license.

Use Node.js 24 or newer:

```powershell
git clone https://github.com/mherub004/mcp-hub.git
cd mcp-hub
npm.cmd ci
Copy-Item .env.saas.example .env.saas
npm.cmd run build
npm.cmd run saas
```

Open **http://127.0.0.1:8080**. SaaS mode keeps its SQLite database under `./data/`.
Google Drive, billing, and email recovery need the credentials described in the
[SaaS setup guide](docs/saas.md). Until email delivery is configured, use an invite code for
non-local testing. For local Docker, run `docker compose -f docker-compose.saas.yml up -d --build`.

### What the hosted product includes

| Capability | Free | Pro |
| --- | ---: | ---: |
| Tracked sources | 3 | 20 |
| Automated check interval | 24 hours | 6 hours |
| Checks per month | 100 | 2,500 |
| MCP requests per month | 300 | 10,000 |

Pro pricing is defined by the recurring Price you create in Stripe; it is shown to customers in
Stripe Checkout. No price is hard-coded in this repository.

## Self-hosted mode

The original single-user MCP Hub remains available. It uses `hub.config.json`, a bearer token,
and the filesystem, Google Drive, and web connectors. This mode is useful for personal setups and
local development. SaaS mode is a separate entry point and does not read `hub.config.json`.

## Why

Every AI assistant needs the same context: your documents, notes and web pages. Configuring
each client separately means duplicated credentials, scattered settings and no single place
to see what is connected.

MCP Hub runs once, holds the connections, and gives every client one endpoint.

```
 Claude ─┐                          ┌─ Google Drive
 ChatGPT ─┼──► MCP Hub (/mcp) ──────┼─ Local files
 Cursor ─┘     one token, one URL   ├─ Web pages
                                    └─ Your connector
```

## Features

- **One endpoint.** A single MCP server at `/mcp` exposes every connector's tools.
- **Simple configuration.** One JSON file. Secrets come from environment variables.
- **Live dashboard.** See connector health, exposed tools and the endpoint URL at `/`.
- **Two transports.** Streamable HTTP for remote clients, stdio for local desktop apps.
- **Secure by default.** Binds to localhost, requires a bearer token for anything non-local,
  and blocks path traversal and private-network fetches.
- **Built-in connectors:** Local files, Google Drive, Web.
- **Easy to extend.** A connector is one TypeScript file with a few methods. See [docs/connectors.md](docs/connectors.md).
- **Ready to deploy.** Dockerfile, Docker Compose, health endpoint and CI included.

## Quick start

Requirements: Node.js 24 or newer.

```bash
git clone https://github.com/mherub004/mcp-hub.git
cd mcp-hub
npm install

cp hub.config.example.json hub.config.json
cp .env.example .env
echo "MCP_HUB_TOKEN=$(openssl rand -hex 32)" >> .env   # or edit .env by hand

npm run dev
```

Open **http://127.0.0.1:3000** to see the dashboard. Your MCP endpoint is
**http://127.0.0.1:3000/mcp**.

Connect a client. For Claude Desktop, Claude Code, Cursor and others, see
[docs/connecting-clients.md](docs/connecting-clients.md).

Full walkthrough: [docs/getting-started.md](docs/getting-started.md).

## Built-in connectors

| Type            | Tools                                   | Needs                          |
| --------------- | --------------------------------------- | ------------------------------ |
| `filesystem`    | `list_files`, `read_file`, `search_files` | A folder on disk             |
| `google-drive`  | `search_files`, `read_file`               | Google OAuth access token    |
| `web`           | `fetch_url`                               | Nothing                      |

Tool names are prefixed with the connector id, for example `notes__search_files` or
`drive__read_file`, so several connectors of the same type can coexist.

## Documentation

| Guide                                                        | What it covers                                  |
| ------------------------------------------------------------ | ----------------------------------------------- |
| [Getting started](docs/getting-started.md)                   | Install, configure and run your first hub       |
| [Configuration](docs/configuration.md)                       | Every config field and environment variable     |
| [Connecting clients](docs/connecting-clients.md)             | Claude, Claude Code, Cursor, ChatGPT and more   |
| [Connectors](docs/connectors.md)                             | Built-in connectors and how to write your own   |
| [HTTP API](docs/api.md)                                      | Endpoints, auth and status response format      |
| [Architecture](docs/architecture.md)                         | How the pieces fit together                     |
| [Deployment](docs/deployment.md)                             | Docker, remote hosting, HTTPS                   |
| [Security](docs/security.md)                                 | Threat model and hardening checklist            |
| [Troubleshooting](docs/troubleshooting.md)                   | Common problems and fixes                       |
| [Roadmap](docs/roadmap.md)                                   | What is planned next                            |

## Project layout

```
mcp-hub/
├── src/
│   ├── index.ts            CLI entry point (HTTP or --stdio)
│   ├── config.ts           Config loading, validation, ${ENV} expansion
│   ├── hub.ts              Connector registry, health checks, MCP server builder
│   ├── server.ts           HTTP routes: /, /mcp, /api/status, /health
│   ├── connector.ts        Connector interface (the extension point)
│   └── connectors/         Built-in connectors
├── public/index.html       Dashboard
├── tests/                  Unit tests (node:test)
├── docs/                   Documentation
└── hub.config.example.json Starter configuration
```

## Development

```bash
npm run dev         # run with reload
npm run typecheck   # strict TypeScript check
npm test            # unit tests
npm run build       # compile to dist/
```

## Contributing

Contributions are welcome, especially new connectors. Read [CONTRIBUTING.md](CONTRIBUTING.md)
first. Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)