1MCP Agent

English

简体中文

English

简体中文

Appearance

Installation ​

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):

bash
# 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 --version

Linux (ARM64 - Raspberry Pi, AWS Graviton):

bash
# 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 --version

macOS (Apple Silicon - M1/M2/M3):

bash
# 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 --version

macOS (Intel):

bash
# 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 --version

Windows (x64 - PowerShell):

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.

bash
# Install globally
npm install -g @1mcp/agent
# or
pnpm add -g @1mcp/agent

# Use directly
npx @1mcp/agent --config mcp.json

Docker ​

You can also run 1MCP using Docker. We provide two image variants:

  • latest: Full-featured image with extra tools (uv, bun) - default
  • lite: 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.

bash
# 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 -d

These 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 ​

bash
# 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.json

Verification ​

Verify installation:

bash
# Binary installation:
1mcp --version

# NPM installation:
npx @1mcp/agent --version

System 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.0 for npm installs; .node-version for source builds

Next Steps ​

Released under the Apache 2.0 License.

Copyright © 2025-present 1MCP