SERVICE

 ____  _____ ______     _____ ____ _____
/ ___|| ____|  _ \ \   / /_ _/ ___| ____|
\___ \|  _| | |_) \ \ / / | | |   |  _|
 ___) | |___|  _ < \ V /  | | |___| |___
|____/|_____|_| \_\ \_/  |___\____|_____|

  MCP Hub & Notification Center

The only MCP server your AI agent needs.

AI agents today juggle a dozen MCP servers: one for GitHub, one for the filesystem, one for search, one for Slack. Every restart, every new project, every new agent has to re-configure all of them. SERVICE solves this. It's a persistent 24/7 background daemon that aggregates all your downstream MCP servers into one unified connection — and layers on a real-time notification gateway so your agents can receive events from X/Twitter, Slack, Email, and webhooks the moment they happen.

One connection. All your tools. Always on.

Why SERVICE?

• 🔌 Single MCP endpoint for everything — Claude Desktop, Cursor, Copilot, and any MCP client connect to one URL (http://localhost:3333/mcp) and instantly get all tools from all your downstream servers, namespaced cleanly (github__create_issue, filesystem__read_file, etc.)

• ⚡ Real-time push, not polling — integrations like Slack, Email, X/Twitter, and webhooks stream events to your agents the moment they arrive via SSE, so agents can react in real-time without burning tokens on polling loops

• 🔒 Local-first and private — all data lives in ~/.service/service.db (SQLite), credentials are AES-256-GCM encrypted, nothing leaves your machine unless you configure it to

• 🧩 Plugin-style integrations — add new integrations via a CLI wizard or the REST API; no rebuild required

Related MCP server: mcp-switchboard

Architecture

AI Agent (Claude Desktop / Cursor / Copilot / any MCP client)
              │
              │  Single MCP connection (Streamable HTTP)
              ▼
┌─────────────────────────────────────────────────────────────┐
│                      SERVICE DAEMON                         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            MCP Hub  ·  port 3333                      │  │
│  │  Aggregates & proxies tools from all downstream MCPs  │  │
│  │  Namespaced tools: github__create_issue, etc.         │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Notification Gateway  ·  port 3334               │  │
│  │  24/7 listener for all integrations                   │  │
│  │  SQLite persistence + SSE push to agents              │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Integration System  (plugin-based)               │  │
│  │  X/Twitter · Slack · Email · Webhooks · HTTP-poll     │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Interactive TUI Dashboard  (Ink v6)              │  │
│  │  Notification Center · Integration Manager ·          │  │
│  │  MCP Manager · Full keyboard navigation               │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                              │
    ┌────┘                              └──────────────────┐
    ▼                                                      ▼
Downstream MCPs (stdio)                      External Platforms
github, filesystem, memory,          X/Twitter, Slack, Email,
brave-search, any MCP server         Webhook, HTTP-poll, custom

Quickstart

# 1. Install globally
npm install -g service-mcp

# 2. Start the daemon
service start

# 3. Add your AI client config (see below)

# 4. Add integrations interactively
service integration add

# 5. Watch it live
service dashboard

Ports: 3333 — MCP Hub (agents connect here) · 3334 — Admin API + SSE stream

Connect Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "service": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Cursor

Edit your Cursor MCP settings (~/.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "service": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Any stdio-compatible client

{
  "mcpServers": {
    "service": {
      "command": "npx",
      "args": ["service-mcp", "mcp-server"]
    }
  }
}

CLI Reference

Daemon Lifecycle

Integration Management

MCP Connection Management

Utilities

Interactive TUI Dashboard

The service dashboard command launches a full-screen, keyboard-driven terminal UI built on Ink v6 (React for CLI — the same framework powering Claude Code and Gemini CLI). It provides complete management of notifications, integrations, and MCP connections without leaving the terminal.

Navigation

Notification Center

Manage all notifications in real-time:

• Real-time updates: New notifications appear instantly via SSE push — no polling

• Visual indicators: ● unread (bold) vs ○ read (dimmed)

• Mark as read: Space marks selected notification, A marks all as read

• Filter: u toggles unread-only view

• Search: / opens inline full-text search (FTS5)

• Detail view: Enter shows full notification body, source, type, and timestamp

Integration Manager

View, configure, and manage all integrations:

• Status badges: 🟢 active / 🔴 error / ⏸ disabled (color-coded)

• Detail view: Shows config fields with secrets redacted as ••••••

• Enable/Disable: e/d keys toggle integration state

• Remove: x key with confirmation dialog

• Add new: a opens in-TUI multi-step form with type selection, schema-driven fields, and password masking for secret fields

MCP Connection Manager

Manage all downstream MCP server connections:

• Status badges: 🟢 connected / 🔴 error / ⏳ connecting, with tool count display

• Detail view: Full command + args, status, and scrollable tool list

• Reconnect: r key triggers reconnect for disconnected MCPs

• Remove: x key with confirmation dialog

• Add new: a opens in-TUI form for name, command, and args

MCP Tool Reference

All built-in SERVICE tools are prefixed with service__. Downstream MCP tools are namespaced as {mcpName}__toolName (e.g. github__create_issue).

Notifications

Agent Memory

MCP Management

System

Platform Tools (Auto-registered from Integrations)

When integrations are active, their tools are automatically registered and available to your agents:

Integration Setup

Webhook

The simplest integration — receives HTTP POST requests and converts them to notifications.

service integration add webhook --name my-webhook
# Returns webhook URL: http://localhost:3334/webhooks/<integration-id>

Send events from any external system:

curl -X POST http://localhost:3334/webhooks/<id> \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy Complete", "body": "v2.1.0 deployed to production"}'

X / Twitter

Requires a Twitter API v2 bearer token. Optional: keyword tracking.

service integration add x
# Wizard prompts for:
#   bearer_token     — Twitter API v2 bearer token
#   track_keywords   — (optional) comma-separated keywords to monitor

Slack

Requires a Slack Bot Token with Socket Mode enabled.

service integration add slack
# Wizard prompts for:
#   bot_token   — xoxb-... (Bot User OAuth Token)
#   app_token   — xapp-... (App-Level Token for Socket Mode)

Scopes required: channels:read, chat:write, reactions:write, channels:history

Email (SMTP + IMAP)

Monitors your inbox via IMAP and sends email via SMTP. Works with Gmail, Outlook, Fastmail, and any standard mail server.

service integration add email
# Wizard prompts for:
#   imap_host, imap_port   — e.g. imap.gmail.com:993
#   smtp_host, smtp_port   — e.g. smtp.gmail.com:587
#   user, password         — your email credentials (stored encrypted)

Tip for Gmail: Enable "App Passwords" in your Google Account security settings.

HTTP Poll

Polls a URL on a schedule and creates a notification whenever the content changes.

service integration add http-poll
# Wizard prompts for:
#   url               — endpoint to poll
#   interval_seconds  — polling interval (e.g. 60)
#   method            — GET or POST

Admin REST API

SERVICE exposes a full REST API on port 3334 for programmatic management and automation:

SSE Event Stream

Subscribe to real-time events:

curl -N http://localhost:3334/events

Events are JSON-encoded NotificationEvent objects pushed as they arrive.

Data Storage

All data is stored locally on your machine. Nothing is sent to external servers unless you configure an integration.

Credentials stored in integrations are encrypted at rest using AES-256-GCM. The encryption key is generated once on first run and stored at ~/.service/.encryption_key.

Examples

See the examples/ directory for ready-to-use configs:

Requirements

Development

# Clone and install
git clone https://github.com/baiehclaca/service-mcp.git
cd service-mcp
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Development mode (watch + auto-reload)
npm run dev

# Lint
npm run lint

Adding a Custom Integration

Every integration implements the IntegrationAdapter interface:

interface IntegrationAdapter {
  id: string
  name: string
  description: string
  configSchema: JSONSchema          // Fields the wizard will prompt for
  connect(config: Record<string, string>): Promise<void>
  disconnect(): Promise<void>
  onEvent(handler: (event: NotificationEvent) => void): void
  getTools(): MCPTool[]             // Tools exposed to agents
}

Register your adapter in src/integrations/index.ts — no rebuild of the core daemon is needed.

License

MIT — © 2024 service-mcp contributors