teamhub-mcp-server

A remote MCP (Model Context Protocol) server that lets multiple people's Claude Code sessions collaborate — see each other's live status, share and search project notes, hand off tasks, and share small durable facts — with per-project, owner-approved access control.

One person hosts it. Everyone else connects to it as a normal remote MCP server with a personal bearer token.

How it works

 Person A's Claude Code  --.
                            +--> teamhub-mcp-server (one Node process, one SQLite file)
 Person B's Claude Code  --'

• Presence is global — everyone can see who's online and what they're doing.

• Everything else (notes, tasks, memory) lives inside a project, which is permissioned. A project's owner has full access; everyone else needs an approved join request at one of two levels:

  • read_only — can view notes, tasks, and memory

  • collaborate — can also post notes, create/claim tasks, and write memory

Nothing is shared by default. Every cross-person data flow is an explicit tool call.

Related MCP server: Claude Orchestrator MCP

Prerequisites

• Node.js >= 20 (tested on 20 and 24)

• npm

• A host machine with persistent disk (VPS, Fly.io, Render, Railway — not classic serverless like Lambda/Vercel functions)

Quick start

1. Clone and install

git clone https://github.com/murali2212/-teamhub-mcp-server.git
cd -teamhub-mcp-server
npm install

2. Build

npm run build

This compiles TypeScript from src/ into dist/.

3. Add users

Each person who will connect needs a bearer token. Generate one per person:

node scripts/add-user.mjs alice
node scripts/add-user.mjs bob

Each command:

• Generates a random token

• Stores only its SHA-256 hash in users.json (never the raw token)

• Prints the raw token once — send it to that person privately

• Prints the exact claude mcp add command they need to run

If a username already exists, the script refuses and tells you to remove the entry manually first (to rotate a token).

4. Start the server

npm start

The server listens on port 3000 by default. Override with the PORT environment variable:

PORT=8080 npm start

5. Each person connects (on their own machine)

Each person runs the command printed by add-user.mjs, which looks like:

claude mcp add --transport http teamhub https://<your-server-url>/mcp \
  --scope user \
  --header "Authorization: Bearer <their-token>"

--scope user makes it available across every project they open in Claude Code. They verify it works with /mcp inside any session.

Environment variables

Deployment

Requirements

• Persistent local disk — SQLite needs a real filesystem. Do NOT deploy to classic serverless (Vercel functions, Netlify functions, AWS Lambda) where the filesystem is ephemeral.

• HTTPS in production — the bearer token travels in a header on every request. Use a reverse proxy (Caddy, nginx + Let's Encrypt) or a tunnel (Cloudflare Tunnel, ngrok) for HTTPS.

• One long-running process — this is not a request-at-a-time function; it's a persistent Node.js server.

Docker

A multi-stage Dockerfile is included:

docker build -t teamhub-mcp-server .
docker run -d \
  -p 3000:3000 \
  -v /path/to/data:/app/data \
  -e TEAMHUB_DB_PATH=/app/data/teamhub.db \
  -e TEAMHUB_USERS_PATH=/app/data/users.json \
  teamhub-mcp-server

Mount a volume for /app/data so the database and users file survive container restarts.

VPS (systemd)

# Build on the server
cd /opt/teamhub-mcp-server
npm install && npm run build

# Create a systemd service
sudo tee /etc/systemd/system/teamhub.service > /dev/null <<EOF
[Unit]
Description=TeamHub MCP Server
After=network.target

[Service]
Type=simple
User=teamhub
WorkingDirectory=/opt/teamhub-mcp-server
ExecStart=/usr/bin/node dist/index.js
Restart=always
Environment=PORT=3000

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable teamhub
sudo systemctl start teamhub

Put Caddy or nginx in front for automatic HTTPS.

Fly.io

fly launch --no-deploy
fly volumes create teamhub_data --size 1
# Edit fly.toml to mount the volume and set env vars
fly deploy

Railway / Render

Point at this repo, set the build command to npm install && npm run build, start command to npm start, and add a persistent disk mounted where TEAMHUB_DB_PATH and TEAMHUB_USERS_PATH point.

All 18 tools

Presence (global, no project needed)

Projects (access control)

Notes (project-scoped)

Tasks (project-scoped)

Memory (project-scoped key-value)

Security

• Tokens hashed at rest — users.json stores SHA-256 hashes, never raw tokens. A leaked file doesn't give working credentials.

• Per-project access control — connecting to the server exposes nothing. Access must be explicitly requested and approved per project.

• Audit trail — every access-affecting event is logged and queryable by the project owner.

• Rate limiting — basic in-memory rate limiter (120 requests per 60-second window per token) guards against runaway loops.

• No internal error leaks — unhandled exceptions return a generic 500, never stack traces.

• Prompt injection mitigation — tool descriptions instruct the calling model to treat shared content as reference data, never as instructions.

Why not OAuth?

Static bearer tokens are a deliberate choice for the scale this targets (2-15 trusted friends/teammates). OAuth 2.1 with dynamic client registration is real infrastructure — disproportionate to "a handful of people I personally invite." If this ever needs self-service signup or untrusted users, that's the point to add OAuth.

Architecture decisions

• Stateless HTTP transport — a fresh MCP server instance per request, no session IDs. Makes the server trivially restartable and safe behind a load balancer. Trade-off: no server-initiated push notifications (pull-based only).

• SQLite (WAL mode) — zero-ops, single file, right-sized for small teams. Not meant to scale past ~15 people.

• AsyncLocalStorage for caller identity — tool handlers get the caller's username via getCaller() without threading it through every function.

• Per-request users.json reload — adding a new teammate doesn't require a server restart.

Project structure

teamhub-mcp-server/
  src/
    index.ts          # Express app, /mcp endpoint, /health, error handling
    auth.ts           # Bearer token auth middleware, rate limiting
    context.ts        # AsyncLocalStorage for per-request caller identity
    db.ts             # SQLite setup, schema, logAudit helper
    access.ts         # requireProjectAccess helper, AccessError class
    tools/
      presence.ts     # teamhub_set_status, teamhub_list_presence
      projects.ts     # Project CRUD, join requests, revoke, audit log
      notes.ts        # Post, get, search notes
      tasks.ts        # Create, list, claim, update tasks
      memory.ts       # Remember and recall key-value facts
  scripts/
    add-user.mjs      # CLI to generate tokens and add users
  Dockerfile          # Multi-stage Docker build
  package.json
  tsconfig.json

License

MIT