Skip to main content

​
Prerequisites

Node.js 20+

UMCP requires Node.js version 20 or higher. Check your version:
node --version

​
Installation Methods

Choose the installation method that best fits your workflow:

​
Verify Installation

Confirm UMCP is installed correctly: 
umcp --help

​
Configuration File

UMCP uses a single JSONC configuration file:
​
Default Path
string
~/.config/umcp/umcp.jsonc
On first run, UMCP automatically creates this file with detailed placeholder examples if it doesn’t exist.

​
Schema Validation

UMCP provides a JSON schema for editor validation and autocomplete: Hosted Schema URL: 
https://raw.githubusercontent.com/grittyninja/umcp/main/umcp.config.schema.json
Usage in config file: 
{
  "$schema": "https://raw.githubusercontent.com/grittyninja/umcp/main/umcp.config.schema.json",
  "categories": {
    // Your configuration here
  }
}
Most modern editors (VS Code, IntelliJ, etc.) will automatically provide autocomplete and validation when the $schema field is present.

​
Config File Format

Only .jsonc files are supported. UMCP will reject .json, .json5, or other formats.
JSONC (JSON with Comments) allows:
  • Single-line comments: // comment
  • Multi-line comments: /* comment */
  • Trailing commas in objects and arrays
Example: 
{
  // This is a comment
  "categories": {
    "web_search": {
      "providers": [
        {
          "name": "brave",
          "transport": "stdio", // Comment here too
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-brave-search"],
        } // Trailing comma allowed
      ]
    }
  }
}

​
Package Structure

When installed, UMCP includes these files: 
umcp/
├── build/              # Compiled JavaScript
│   ├── index.js       # CLI entry point
│   ├── cli.js
│   ├── config.js
│   ├── serve.js
│   └── ...
├── README.md
├── umcp.config.schema.json
└── examples/
    └── umcp.config.jsonc

​
Troubleshooting

If you encounter npm permission errors, use one of these solutions:Option 1: Use npx (recommended)
npx github:grittyninja/umcp serve
Option 2: Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Option 3: Use UMCP’s fallback cacheUMCP automatically applies a fallback npm cache at ~/.cache/umcp/npm when it detects permission issues.
Node.js is not installed or not in your PATH.Install Node.js:
  • macOS: brew install node
  • Ubuntu/Debian: sudo apt install nodejs npm
  • Windows: Download from nodejs.org
Verify installation:
node --version
npm --version
Rebuild the project:
cd umcp
rm -rf node_modules build
npm install
npm run build
UMCP creates the config file automatically on first run. To trigger creation:
umcp validate
This will create ~/.config/umcp/umcp.jsonc with example configuration.You can also specify a custom path:
umcp validate --config /path/to/my-config.jsonc

​
Next Steps

Quick Start Guide

Get UMCP running in under 5 minutes

Configuration

Learn how to configure providers and tools

CLI Reference

Explore all CLI commands and options

Examples

See real-world configuration examples

Build docs developers (and LLMs) love

Get started for freeTalk to us