Installation
Binary Downloads (Recommended)
Download the standalone binary for your platform - no Node.js required!
Supported Platforms
- Linux (x64):
1mcp-linux-x64 - Linux (ARM64):
1mcp-linux-arm64 - Windows (x64):
1mcp-win32-x64.exe - macOS (ARM64):
1mcp-darwin-arm64 - macOS (Intel):
1mcp-darwin-x64
Quick Installation
Linux (x64):
# Download and extract archive
curl -L -o 1mcp-linux-x64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-x64.tar.gz
tar -xzf 1mcp-linux-x64.tar.gz
sudo mv 1mcp-linux-x64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp
# Clean up
rm 1mcp-linux-x64.tar.gz
# Verify installation
1mcp --versionLinux (ARM64 - Raspberry Pi, AWS Graviton):
# Download and extract archive
curl -L -o 1mcp-linux-arm64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-linux-arm64.tar.gz
tar -xzf 1mcp-linux-arm64.tar.gz
sudo mv 1mcp-linux-arm64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp
# Clean up
rm 1mcp-linux-arm64.tar.gz
# Verify installation
1mcp --versionmacOS (Apple Silicon - M1/M2/M3):
# Download and extract archive
curl -L -o 1mcp-darwin-arm64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-darwin-arm64.tar.gz
tar -xzf 1mcp-darwin-arm64.tar.gz
sudo mv 1mcp-darwin-arm64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp
# Clean up
rm 1mcp-darwin-arm64.tar.gz
# Verify installation
1mcp --versionmacOS (Intel):
# Download and extract archive
curl -L -o 1mcp-darwin-x64.tar.gz https://github.com/1mcp-app/agent/releases/latest/download/1mcp-darwin-x64.tar.gz
tar -xzf 1mcp-darwin-x64.tar.gz
sudo mv 1mcp-darwin-x64 /usr/local/bin/1mcp
sudo chmod +x /usr/local/bin/1mcp
# Clean up
rm 1mcp-darwin-x64.tar.gz
# Verify installation
1mcp --versionWindows (x64 - PowerShell):
# Download and extract archive
Invoke-WebRequest -Uri "https://github.com/1mcp-app/agent/releases/latest/download/1mcp-win32-x64.zip" -OutFile "1mcp-win32-x64.zip"
Expand-Archive -Path "1mcp-win32-x64.zip" -DestinationPath "."
# Option 1: Use directly
.\1mcp-win32-x64.exe --version
# Option 2: Add to PATH for global access
# Move to a directory in PATH (e.g., C:\Windows\System32 or create a new directory)
# Then you can use: 1mcp --version
# Clean up
Remove-Item "1mcp-win32-x64.zip"Manual Download:
Visit the latest release page and download the appropriate binary for your platform.
Benefits
- ✅ No Dependencies: No Node.js installation required
- ✅ Fast Startup: Instant execution, no package resolution
- ✅ Portable: Platform-specific executable that can run without a Node.js installation
- ✅ Release Builds: Platform archives are built by the release workflow
- ✅ Compressed Archives: tar.gz/zip format for faster downloads (~67% smaller)
- ✅ Platform Coverage: Linux and macOS support x64 and ARM64; Windows releases support x64
- ✅ Standard Formats: No special extraction tools needed, works everywhere
Package Managers
npm/pnpm
The npm install path requires Node.js ^20.19.0 || ^22.12.0 || >=23.0.0.
# Install globally
npm install -g @1mcp/agent
# or
pnpm add -g @1mcp/agent
# Run the installed command
1mcp --config mcp.jsonAlternative: run without a global installation
Examples throughout these docs assume 1mcp is installed and available on PATH. If you prefer not to install it globally, replace 1mcp with npx -y @1mcp/agent for a one-off command:
npx -y @1mcp/agent --version
npx -y @1mcp/agent serve --config mcp.jsonFor a client launch configuration, the equivalent alternative is "command": "npx" with "args": ["-y", "@1mcp/agent", "proxy"]. GUI applications may need the absolute path to the installed executable if their PATH differs from your terminal's.
Docker
You can also run 1MCP using Docker. We provide two image variants:
latest: Full-featured image with extra tools (uv, bun) - defaultlite: Lightweight image with basic Node.js package managers only (npm, pnpm, yarn)
Keep mcp.json and the optional sibling config.toml in a dedicated directory. The directory is mounted writable so mcp add and mcp update can persist changes.
# Prepare the container configuration directory
mkdir -p 1mcp-config
cp mcp.json 1mcp-config/
# If you use application settings such as auth: cp config.toml 1mcp-config/
# Pull and run (full image); publish only on the host loopback interface
docker run -p 127.0.0.1:3050:3050 \
-e ONE_MCP_HOST=0.0.0.0 \
-e ONE_MCP_PORT=3050 \
-e ONE_MCP_EXTERNAL_URL=http://127.0.0.1:3050 \
-e ONE_MCP_CONFIG=/usr/src/app/config/mcp.json \
-v "$(pwd)/1mcp-config:/usr/src/app/config" \
ghcr.io/1mcp-app/agent:latest
# Pull and run (lite image) with proper networking
docker run -p 127.0.0.1:3050:3050 \
-e ONE_MCP_HOST=0.0.0.0 \
-e ONE_MCP_PORT=3050 \
-e ONE_MCP_EXTERNAL_URL=http://127.0.0.1:3050 \
-e ONE_MCP_CONFIG=/usr/src/app/config/mcp.json \
-v "$(pwd)/1mcp-config:/usr/src/app/config" \
ghcr.io/1mcp-app/agent:lite
# For users in China - faster package installation
docker run -p 127.0.0.1:3050:3050 \
-e ONE_MCP_HOST=0.0.0.0 \
-e ONE_MCP_PORT=3050 \
-e ONE_MCP_EXTERNAL_URL=http://127.0.0.1:3050 \
-e npm_config_registry=https://registry.npmmirror.com \
-e UV_INDEX=http://mirrors.aliyun.com/pypi/simple \
-e UV_DEFAULT_INDEX=http://mirrors.aliyun.com/pypi/simple \
-e ONE_MCP_CONFIG=/usr/src/app/config/mcp.json \
-v "$(pwd)/1mcp-config:/usr/src/app/config" \
ghcr.io/1mcp-app/agent:latest
# With docker-compose (recommended)
cat > docker-compose.yml << 'EOF'
services:
1mcp:
image: ghcr.io/1mcp-app/agent:latest
ports:
- "127.0.0.1:3050:3050"
volumes:
- ./1mcp-config:/usr/src/app/config
environment:
- ONE_MCP_HOST=0.0.0.0
- ONE_MCP_PORT=3050
- ONE_MCP_EXTERNAL_URL=http://127.0.0.1:3050
- ONE_MCP_LOG_LEVEL=info
- ONE_MCP_CONFIG=/usr/src/app/config/mcp.json
# Optional: For users in China mainland
# - npm_config_registry=https://registry.npmmirror.com
# - UV_INDEX=http://mirrors.aliyun.com/pypi/simple
# - UV_DEFAULT_INDEX=http://mirrors.aliyun.com/pypi/simple
# Optional: Behind corporate proxy
# - https_proxy=${https_proxy}
# - http_proxy=${http_proxy}
EOF
docker compose up -dThese examples are reachable only from the Docker host. Before publishing 1MCP on another interface, enable authentication in 1mcp-config/config.toml, set ONE_MCP_EXTERNAL_URL to the public HTTPS URL, and follow the Authentication guide. Binding a runtime beyond loopback without authentication exposes its MCP capabilities to the network.
Available Tags
Full-Featured Images:
latest,vX.Y.Z,vX.Y,vX
Lightweight Images:
lite,vX.Y.Z-lite,vX.Y-lite,vX-lite
Image Details
Full Image (latest):
- Node.js (version from
.node-version) - npm, pnpm, yarn
- uv (Python package manager)
- bun (JavaScript runtime)
- curl, python3, bash
Lite Image (lite):
- Node.js (version from
.node-version) - npm, pnpm, yarn only
- Smaller size, faster downloads
Build from Source
Prerequisites
- Node.js at the version recorded in
.node-version - The repository version is the supported source-build environment, not a published package support contract.
- pnpm package manager
Build Steps
# Clone repository
git clone https://github.com/1mcp-app/agent.git
cd agent
# Install dependencies
pnpm install
# Build
pnpm build
# Run
node build/index.js --config mcp.jsonVerification
Verify installation:
# Binary or global npm/pnpm installation:
1mcp --versionSystem Requirements
For Binary Installation:
- Memory: 256MB RAM minimum, 1GB recommended
- Disk: Minimal space (single binary + config files)
- Network: HTTP/HTTPS outbound access for MCP servers
- OS: Linux (x64/ARM64), Windows (x64), macOS (ARM64/x64)
For NPM Installation:
- Memory: 512MB RAM minimum, 2GB recommended
- Disk: Space for Node.js dependencies and logs
- Network: HTTP/HTTPS outbound access for MCP servers
- OS: Linux (x64/ARM64), macOS (ARM64/x64), Windows (x64)
- Runtime: Node.js
^20.19.0 || ^22.12.0 || >=23.0.0for npm installs;.node-versionfor source builds
Next Steps
- Quick Start Guide - Get running in 5 minutes
- Configuration - Detailed setup options
