universal-mcp-toolkit

English · 简体中文 · Español · 日本語 · 한국어 · Français · Deutsch · Português · Русский · हिन्दी · العربية

The canonical open-source monorepo for production-ready Model Context Protocol servers.

If you have ever wanted one place to find great MCP servers for GitHub, Slack, Notion, databases, cloud platforms, research sources, and local files without stitching together a dozen half-finished repos, this is it.

🔗 Part of the AI Trio

universal-mcp-toolkit is one of three sibling projects that compose into a complete agent memory + tooling stack:

Project	Role
universal-mcp-toolkit	MCP protocol, server registry, and tool routing
memos	Graph-based persistent memory across agent sessions
llm-guardian	Token-cost guardian that compresses prompts and injects MemOS memory slices

Together they cover transport + tools (UMT), memory + persistence (MemOS), and LLM inference cost control (llm-guardian). The MemOS MCP adapter is published as @mem-os/sdk and pairs directly with UMT's link memos command.

⚡ Quick Start

The fastest way to get going:

bash

# See all 27 available servers
npx universal-mcp-toolkit list

# Interactive setup — pick your servers, choose transport, write config
npx universal-mcp-toolkit install

# Generate a Claude Desktop config snippet
npx universal-mcp-toolkit config --server github slack filesystem --target claude-desktop

# Run a server locally
npx universal-mcp-toolkit run github --transport stdio

# Check your environment before debugging
npx universal-mcp-toolkit doctor github

# Validate a reviewable cross-server workflow
npx universal-mcp-toolkit workflow validate examples/workflows/github-search-to-slack.json

For a guided setup walkthrough, open docs/getting-started.html. For deterministic composition, see docs/workflows.md.

Or install globally:

Terminal

npm install -g universal-mcp-toolkit
umt list

Or install from CodeGuilds — the community registry for AI developer tools:

bash

codeguilds install universal-mcp-toolkit

Why this exists

The MCP ecosystem is exploding, but the developer experience is still fragmented.

Most repos solve one narrow integration.
Many servers stop at a demo-quality tool or two.
Transport support, auth handling, docs, and packaging are wildly inconsistent.
There is no obvious reference implementation that shows how a serious MCP monorepo should feel.

universal-mcp-toolkit fixes that with one opinionated, high-quality Turborepo:

28 production-focused MCP servers
One shared strict-mode TypeScript core
One polished CLI for install, config, run, and diagnostics
Consistent Zod validation, structured errors, and pino logging
Stdio plus HTTP+SSE support across the toolkit
Discovery-friendly .well-known/mcp-server.json server cards

What makes this worth starring

Tool discovery — umt tools list finds any MCP tool across 27+ servers by name or category
Deterministic workflows — umt workflow validate|run executes reviewable, versioned JSON workflows with strict input and step references
Server composition — umt compose remains available for quick two-step output piping
Standards-aligned discovery — umt discover --registry reads official MCP Registry-compatible endpoints alongside local and well-known discovery
Enforced tool boundaries — bridge allowlists and RBAC policies are checked before cache lookup, reconnect, or remote execution
TTL + LRU caching — MCPFunctionCallingBridge caches results by tool+args, avoiding redundant API calls
Health monitoring — transport failures feed the circuit breaker without treating ordinary tool validation errors as connection failures
Buffered result chunks — callToolStreaming() exposes completed results through an async chunk iterator; it does not claim protocol-level streaming
Multi-server sessions — Session class orchestrates tools across multiple MCP servers with parallel calls
Lazy plugin loading — server packages loaded on-demand, not statically bundled
Lazy tool registration — registerLazyTool defers expensive initialization until a tool is actually called
Structured error context — bridge errors include tool name, args, and error type for easier debugging
Type-safe chaining — callToolChain with ToolChain types enables compile-time-checked tool pipelines
Real developer utility right now
Great default ergonomics for Claude Desktop, Cursor, and local workflows
A single architecture you can learn once and extend everywhere
Strong package hygiene with exports maps, keywords, build scripts, and test hooks
A repo designed to be both a product and a reference implementation

The short version

Category	What you get
Core runtime	`@universal-mcp-toolkit/core` with typed tool registration, env loading, Zod validation, integration manifests, pino logging, stdio and HTTP runtime bootstrapping
Unified CLI	`universal-mcp-toolkit` with `list`, `config`, `install`, `run`, `tools list`, `workflow`, `compose`, `discover`, and `doctor`
Collaboration servers	GitHub, Notion, Slack, Linear, Jira, Discord, Trello
Productivity servers	Google Calendar, Google Drive
Media and commerce servers	Spotify, Stripe
Data servers	PostgreSQL, MongoDB, Redis, Supabase, Airtable
Platform servers	Vercel, Cloudflare Workers, Docker, npm Registry
Research and local servers	Hacker News, arXiv, FileSystem
Memory server	MemOS local persistent memory

Experimental companion packages under the @contextcore/* scope currently include Notion, Slack, Playwright, and OpenAI variants used for a separate publish line and testing lane.

Comparison

Option	Breadth	DX quality	Shared architecture	Host config help	Documentation polish	Tool discovery	Server composition	Caching	Lazy loading	Remote MCP discovery	Resilient transport	Token budgeting
`universal-mcp-toolkit`	28 servers in one monorepo	High	Yes	Yes	Yes	✅ `umt tools list`	✅ `umt compose`	✅ TTL+LRU	✅ `registerLazyTool`	✅ `umt discover --remote`	✅ Auto-reconnect + circuit breaker	✅ `TokenBudgetManager`
Single-service MCP repos	Narrow	Varies	No	Rarely	Usually none	❌	❌	❌	❌	❌	❌	❌
Personal one-off scripts	Very narrow	Low	No	No	No	Usually none	❌	❌	❌	❌	❌	❌

Supported servers

Server	Focus	Primary required env
GitHub	Repositories, pull requests, workflows, search	`GITHUB_TOKEN`
Notion	Pages, databases, structured docs	`NOTION_TOKEN`
Slack	Channels, history, messaging	`SLACK_BOT_TOKEN`
Linear	Issue triage and planning	`LINEAR_API_KEY`
Jira	Tickets, workflow transitions, incident triage	`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
Google Calendar	Calendars, events, meeting workflows	`GOOGLE_CALENDAR_ACCESS_TOKEN`
Google Drive	Search, metadata, exports	`GOOGLE_DRIVE_ACCESS_TOKEN`
Spotify	Playback, search, playlists	`SPOTIFY_ACCESS_TOKEN`
Stripe	Customers, invoices, subscriptions	`STRIPE_SECRET_KEY`
PostgreSQL	Tables, schema inspection, guarded queries	`POSTGRESQL_URL`
MongoDB	Collections, document reads, aggregation	`MONGODB_URI`
Redis	Keys, TTLs, cache diagnostics	`REDIS_URL`
Supabase	Tables, storage, project access	`SUPABASE_URL`, `SUPABASE_KEY`
Vercel	Projects, deployments, environments	`VERCEL_TOKEN`
Cloudflare Workers	Workers, routes, edge rollouts	`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`
Docker	Containers, images, daemon state	none required
npm Registry	Search, metadata, versions, dist-tags	none required
Hacker News	Top stories, search, threads	none required
arXiv	Paper search and reading lists	none required
FileSystem	Safe local file search, reads, writes	`FILESYSTEM_ROOTS`
MemOS	Local-first persistent memory over MCP	none required
Discord	Guilds, channels, messages, members	`DISCORD_BOT_TOKEN`
Airtable	Tables, records, CRUD operations	`AIRTABLE_API_KEY`, `AIRTABLE_BASE_ID`
Trello	Boards, lists, cards, archiving	`TRELLO_API_KEY`, `TRELLO_TOKEN`
Playwright	Browser automation and web scraping	`PLAYWRIGHT_BROWSERS_PATH` (optional)
OpenAI	Chat completions, embeddings, and model queries	`OPENAI_API_KEY`

Some servers also expose optional tuning variables such as POSTGRESQL_ALLOW_WRITES, REDIS_ALLOW_WRITES, MONGODB_ALLOW_WRITE_PIPELINES, VERCEL_TEAM_ID, or FILESYSTEM_MAX_READ_BYTES. The root .env.example includes the most useful knobs.

Community opt-in servers

The bundled list above is curated and dependency-pinned. Third-party MCP servers can be added as opt-in entries using the same mcpServers config shape — just point npx at the external package. They are not part of the default bundle.

Vynly (`@vynly/mcp`)

Vynly is a social network purpose-built for AI-generated images and short video. Its MCP server (@vynly/mcp, by @Vovala14) exposes a public posting API with a free demo token on first call (no signup) and handles provenance verification (C2PA / SynthID / generator EXIF) automatically — useful when you want an agent to publish output anywhere with provenance baked in.

Opt-in only: Vynly is not bundled in the default config. Add it to your host config (Claude Desktop, Cursor, or any MCP client) as a normal npx server:

config.json

{
  "mcpServers": {
    "vynly": {
      "command": "npx",
      "args": ["-y", "@vynly/mcp"],
      "env": {
        "VYNLY_TOKEN": "${VYNLY_TOKEN}"
      }
    }
  }
}

Grab a free demo token (no signup) before first use:

Terminal

curl -X POST https://vynly.co/api/agents/demo-token

Then generate or merge the snippet with:

bash

corepack pnpm --filter universal-mcp-toolkit exec umt config --server vynly --target claude-desktop --mode workspace

(If umt does not yet know the vynly server id, paste the JSON above directly into your host config — the runtime is the same npx -y @vynly/mcp launch.)

Repository layout

universal-mcp-toolkit/ ├─ packages/ │ ├─ core/ │ ├─ bridge/ │ └─ cli/ ├─ docs/ │ ├─ index.html │ └─ getting-started.html ├─ servers/ │ ├─ github/ │ ├─ notion/ │ ├─ slack/ │ ├─ linear/ │ ├─ jira/ │ ├─ google-calendar/ │ ├─ google-drive/ │ ├─ spotify/ │ ├─ stripe/ │ ├─ postgresql/ │ ├─ mongodb/ │ ├─ redis/ │ ├─ supabase/ │ ├─ vercel/ │ ├─ cloudflare-workers/ │ ├─ docker/ │ ├─ npm-registry/ │ ├─ hackernews/ │ ├─ arxiv/ │ ├─ discord/ │ ├─ airtable/ │ ├─ trello/ │ └─ filesystem/ ├─ turbo.json ├─ pnpm-workspace.yaml └─ README.md

Code


## Quick start

### Clone and install

```bash
git clone https://github.com/Markgatcha/universal-mcp-toolkit.git
cd universal-mcp-toolkit
corepack pnpm install

Build the workspace

bash

corepack pnpm build

Explore what is available

bash

corepack pnpm --filter universal-mcp-toolkit exec umt list

Generate a host config snippet

bash

corepack pnpm --filter universal-mcp-toolkit exec umt config --server github slack filesystem --target claude-desktop --mode workspace

Run a server locally

bash

corepack pnpm --filter universal-mcp-toolkit exec umt run github --transport stdio

Check your environment

bash

corepack pnpm --filter universal-mcp-toolkit exec umt doctor github

CLI experience

The CLI is designed to feel like a real product, not a pile of scripts.

`umt list`

See every available server, grouped by category with required environment variables and descriptions.

`umt config`

Generate ready-to-paste JSON for Claude Desktop, Cursor, or any MCP-compatible host config flow.

`umt install`

Run an interactive setup flow, choose servers, choose npx or workspace mode, write the result to disk, and save the profile for later reference.

`umt run`

Launch any built workspace server locally with stdio or HTTP+SSE transport.

The --supervise flag enables crash-loop detection and automatic restarts:

umt run github --transport stdio --supervise

If the server crashes 5 times within 60 seconds it stops retrying. Logs are written to the state directory under logs/<serverId>.log and can be tailed with umt logs <serverId>.

`umt doctor`

Check build output, config state, and required environment variables before you waste time debugging a missing token or missing dist file.

New in v1.1.0+

Command	What it does
`umt status`	Show currently running umt server processes and their PIDs
`umt logs <server>`	Tail the log file for a specific server
`umt test <server>`	Run a live end-to-end MCP handshake test against a server
`umt conformance [server]`	Check registry config and live stdio handshakes where local build output exists
`umt workflow validate <file>`	Validate a versioned JSON workflow without starting any server
`umt workflow run <file> --input <json>`	Execute a validated workflow sequentially and disconnect every step safely
`umt discover --registry [url]`	Include official or private MCP Registry-compatible entries in discovery
`umt search <query>`	Search available servers by name, description, and tags
`umt init`	Interactive setup wizard for new users
`umt update`	Check npm for a newer version of the CLI and optionally install it
`umt upgrade`	Check npm for newer versions of individual server packages
`umt export`	Export install profiles to a portable JSON file (no secrets included)
`umt export-config`	Export current server config in a specific client format
`umt link`	Link a local MemOS/ContextCore SQLite memory database
`umt profile create <name>`	Create a new named profile with interactive wizard
`umt profile show [name]`	Show profile configuration details
`umt profile export <name>`	Export a named profile to a JSON file
`umt profile import <path>`	Import a profile from a JSON file

Configuration examples

Claude Desktop

Paste a generated snippet into your Claude Desktop config file. On Windows, that is commonly:

text

%APPDATA%\Claude\claude_desktop_config.json

On macOS, use ~/Library/Application Support/Claude/claude_desktop_config.json. On Linux, use ~/.config/Claude/claude_desktop_config.json.

The JSON examples below use literal placeholders like ${GITHUB_TOKEN}. Replace them with real values before pasting into your host config.

Example:

config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@universal-mcp-toolkit/server-github", "--transport", "stdio"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@universal-mcp-toolkit/server-filesystem", "--transport", "stdio"],
      "env": {
        "FILESYSTEM_ROOTS": "${FILESYSTEM_ROOTS}"
      }
    }
  }
}

Cursor

Generate the same mcpServers snippet and place it into the MCP config file you use for Cursor. The CLI keeps the format host-friendly and consistent, so the same generated JSON works well as a reusable snippet:

config.json

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@universal-mcp-toolkit/server-slack", "--transport", "stdio"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    },
    "linear": {
      "command": "npx",
      "args": ["-y", "@universal-mcp-toolkit/server-linear", "--transport", "stdio"],
      "env": {
        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
      }
    }
  }
}

Transport model

Every server in the toolkit is designed around the same transport story:

stdio for local child-process integrations
Streamable HTTP for current remote MCP integrations
HTTP+SSE retained as a legacy compatibility transport
discovery metadata exposed through package cards and Registry-compatible metadata

The shared core handles runtime bootstrapping, logging, env loading, and tool registration so every server behaves consistently.

MCP Registry Discovery

UMT is discoverable through three complementary manifest paths so it shows up in registry search, Smithery, and direct well-known lookups:

Official MCP Registry — registry-server.json at the repo root uses the reverse-DNS name io.github.markgatcha.universal-mcp-toolkit and lists the tool surface, transports, and environment variables. Submit it to the official registry to appear in mcp-cli search results.
Smithery auto-discovery — .well-known/mcp/server-card.json is the well-known server card that Smithery (and any RFC-style crawler) fetches to build a live profile. Keep version and description in sync with packages/cli/package.json.
Runtime .well-known/mcp-server.json — the discovery document served by the running server; bumped to 1.6.28 with the updated registry description.

bash

# Search the official MCP Registry together with local discoveries
umt discover --registry

# Use a private or alternate Registry-compatible endpoint
umt discover --registry https://registry.example.com/v0.1/servers

# Verify the well-known card is served correctly
curl http://localhost:3000/.well-known/mcp/server-card.json | jq .name

Core package

@universal-mcp-toolkit/core is the part you will want to study if you are building your own MCP servers.

It includes:

ToolkitServer base class
defineTool<TInput, TOutput> helper
loadEnv() for strict configuration validation
HttpServiceClient for typed fetch-based integrations
createServerCard() for discovery metadata
validateIntegrationManifest() and summarizeIntegrationReadiness() for versioned integration evidence
parseRuntimeOptions() and runToolkitServer() for stdio and HTTP launch flows
pino logging configured for stderr-safe server operation

See docs/integration-contract.md for the additive integration contract and readiness model.

Engineering standards

TypeScript strict mode across the workspace
Zod schemas for input and output validation
Explicit structured errors for config, validation, and upstream failures
Consistent package manifests with exports maps and keywords
Server cards under .well-known/
Turborepo orchestration for build, typecheck, test, and clean flows

Release philosophy

This repo is meant to be the reference implementation developers point to when they ask:

What should a serious MCP monorepo look like?
How should server packages be documented and discovered?
How do you keep 20 integrations consistent without turning the codebase into a mess?

The answer should be: clone this repo, run the CLI, read the core package, and adapt the parts you need.

Development workflow

bash

corepack pnpm install
corepack pnpm build
corepack pnpm typecheck
corepack pnpm test

Bun (also supported)

bun install
bun run build
bun run packages/cli/dist/index.js --version

Use Turbo filters when you only want to work on one package:

bash

corepack pnpm --filter @universal-mcp-toolkit/core build
corepack pnpm --filter universal-mcp-toolkit typecheck
corepack pnpm --filter @universal-mcp-toolkit/server-github test

If you only want the onboarding path, start with docs/getting-started.html.

Package highlights

`packages/core`

Shared runtime primitives and strict abstractions for server authors.

`packages/bridge`

Connect any MCP server to any LLM provider — OpenAI, Anthropic, or Ollama function-calling format. Includes health monitoring, circuit breakers, RBAC, audit logging, TTL+LRU caching, and a full agent conversation loop. Use with the Vercel AI SDK via @universal-mcp-toolkit/ai-sdk.

`packages/ai-sdk`

Adapter that lets you use UMT's MCP tools directly with the Vercel AI SDK's streamText() and generateText() functions. Zero boilerplate — turn any MCP server into AI SDK tools in one line.

`packages/cli`

The operator console for listing, configuring, installing, running, and diagnosing the entire toolkit.

`servers/*`

27 independently publishable MCP server packages that all share the same operational shape.

Roadmap direction

The monorepo is intentionally structured so it can grow without losing coherence.

Add more servers without inventing a new architecture every time
Improve server cards as discovery standards evolve
Expand host config templates as more MCP clients standardize their formats
Deepen smoke and contract tests across transports

Community

Please read CODE_OF_CONDUCT.md before participating in issues, pull requests, reviews, or discussions. The project aims to stay both technically rigorous and welcoming to contributors at every experience level.

Persistent Memory

Pair universal-mcp-toolkit with MemOS for persistent, graph-based memory across agent sessions.

bash

# Add persistent memory to your MCP agents
pip install memos
npm install @mem-os/sdk

# Generate a ready-to-paste MemOS MCP config
npx universal-mcp-toolkit link memos --db-path ~/.memos/memos.db

MemOS acts as the memory layer for your MCP stack — every tool call, result, and context your agent produces can be stored, retrieved, and searched across restarts and sessions. The MemOS MCP adapter runs through npx -y @mem-os/sdk mcp.

Layer	Tool	Role
Transport & Tools	universal-mcp-toolkit	MCP protocol, server registry, tool routing
Memory & Persistence	MemOS	Graph-based persistent memory across sessions
LLM Inference	Ollama / any LLM	Local model execution

⭐ Star History

💬 Used By the Community

Building something with universal-mcp-toolkit? We'd love to know.

Open a Discussion and tell us:

What you're building
Which servers you're using
Any integrations or workflows you've set up

You might get featured here.

Known uses

Claude Desktop + GitHub + FileSystem — local dev assistant that reads repos and writes to disk
Cursor + PostgreSQL + Supabase — database-aware AI code completion
Paired with MemOS — persistent agent memory across sessions

📦 Show & Tell

If you've created a custom server, workflow, or integration using this toolkit as a base, open a PR to add it to the Wiki or start a Discussion. The best examples will be highlighted in the README.

🌐 Community

Website: context-core.dev/umt
Discord: discord.gg/DyQGgPuueu — real-time help and release chatter
Twitter/X: @Context_Core

⭐ Star history

If UMT saves you from stitching together a dozen half-finished MCP repos, consider the star — it keeps the project visible.

License

MIT — see LICENSE for full terms.

universal-mcp-toolkit

🔗 Part of the AI Trio

⚡ Quick Start

Why this exists

What makes this worth starring

The short version

Comparison

Supported servers

Community opt-in servers

Vynly (@vynly/mcp)

Repository layout

Build the workspace

Explore what is available

Generate a host config snippet

Run a server locally

Check your environment

CLI experience

umt list

umt config

umt install

umt run

umt doctor

New in v1.1.0+

Configuration examples

Claude Desktop

Cursor

Transport model

MCP Registry Discovery

Core package

Engineering standards

Release philosophy

Development workflow

Bun (also supported)

Package highlights

packages/core

packages/bridge

packages/ai-sdk

packages/cli

servers/*

Roadmap direction

Community

Persistent Memory

⭐ Star History

💬 Used By the Community

Known uses

📦 Show & Tell

🌐 Community

⭐ Star history

License

Vynly (`@vynly/mcp`)

`umt list`

`umt config`

`umt install`

`umt run`

`umt doctor`

`packages/core`

`packages/bridge`

`packages/ai-sdk`

`packages/cli`

`servers/*`