Skip to main content

Installation

Prerequisites​

Before installing vMCP, ensure you have:

  • Python 3.11+ - Required for the backend
  • PostgreSQL - Database for storing vMCP configurations and logs
  • Node.js 20+ - Required for the frontend (optional if using pre-built distribution)

The easiest way to run vMCP is using uvx:

uvx vmcp run

This single command will:

  1. Download and install vMCP
  2. Set up the database
  3. Start all services
  4. Open your browser to the web interface

Docker Installation​

Run vMCP using Docker for a fully containerized setup:

docker compose up

The docker-compose.yml includes:

  • PostgreSQL database
  • FastAPI backend
  • Frontend (served by backend)

Access the interface at: http://localhost:8000

Manual Installation​

For development or custom deployments:

1. Clone the Repository​

git clone https://github.com/vmcp/vmcp.git
cd vmcp

2. Set Up the Backend​

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

3. Configure Database​

Create a .env file in the backend directory:

DATABASE_URL=postgresql://vmcp:vmcp@localhost:5432/vmcp
LOG_LEVEL=INFO

Initialize the database:

# Start PostgreSQL
docker run -d \
  --name vmcp-postgres \
  -e POSTGRES_USER=vmcp \
  -e POSTGRES_PASSWORD=vmcp \
  -e POSTGRES_DB=vmcp \
  -p 5432:5432 \
  postgres:16

# Run migrations
alembic upgrade head

4. Build the Frontend​

cd ../frontend
npm install
npm run build

The built files will be placed in frontend/dist and served by the backend.

5. Start the Backend​

cd ../backend
python -m vmcp.main

The server will start on http://localhost:8000

Verify Installation​

Once vMCP is running, verify the installation:

  1. Open http://localhost:8000 in your browser
  2. You should see the vMCP interface
  3. Navigate to the "Connections" page to add your first MCP server
  4. Create a vMCP on the "vMCPs" page

Environment Variables​

Key environment variables for configuration:

VariableDescriptionDefault
DATABASE_URLPostgreSQL connection stringpostgresql://vmcp:vmcp@localhost:5432/vmcp
LOG_LEVELLogging level (DEBUG, INFO, WARNING, ERROR)INFO
HOSTBackend host0.0.0.0
PORTBackend port8000
FRONTEND_DIRPath to frontend build directory../frontend/dist

Troubleshooting​

Database Connection Issues​

If you see database connection errors:

# Check PostgreSQL is running
docker ps | grep postgres

# Test connection
psql -h localhost -U vmcp -d vmcp

Port Already in Use​

If port 8000 is already in use:

# Change the port in .env
PORT=8001

# Or use environment variable
PORT=8001 python -m vmcp.main

Frontend Not Loading​

Ensure the frontend was built successfully:

cd frontend
ls -la dist/  # Should show index.html and assets/

Next Steps​