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)

## Quick Install (Recommended)​

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:

Variable | Description | Default
--- | --- | ---
`DATABASE_URL` | PostgreSQL connection string | `postgresql://vmcp:vmcp@localhost:5432/vmcp`
`LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO`
`HOST` | Backend host | `0.0.0.0`
`PORT` | Backend port | `8000`
`FRONTEND_DIR` | Path 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​

- Creating Your First vMCP
- Connecting MCP Servers
- Configuration Guide