Skip to main content

Installation

This guide will help you install and run MCPulse. Choose the method that best fits your needs.

Prerequisites​

Before you begin, ensure you have:

  • Docker & Docker Compose (recommended) - Version 20.10+
  • OR for manual installation:
    • Go 1.21 or higher
    • TimescaleDB 16+

The fastest way to get MCPulse running is using the pre-built Docker images. MCPulse images are available on:

  • GitHub Container Registry: ghcr.io/sirrobot01/mcpulse
  • Docker Hub: cy01/mcpulse

Step 1: Pull the Docker Image​

Choose either GitHub Container Registry or Docker Hub:

# From GitHub Container Registry (recommended)
docker pull ghcr.io/sirrobot01/mcpulse:latest

# Or from Docker Hub
docker pull cy01/mcpulse:latest

Step 2: Create Docker Compose Configuration​

Create a docker-compose.yml file:

version: '3.8'

services:
  timescaledb:
    image: timescale/timescaledb:latest-pg16
    environment:
      POSTGRES_DB: mcp_analytics
      POSTGRES_USER: mcp_user
      POSTGRES_PASSWORD: changeme  # Change this!
    ports:
      - "5432:5432"
    volumes:
      - mcpulse-data:/var/lib/postgresql/data

  mcpulse:
    image: ghcr.io/sirrobot01/mcpulse:latest  # or cy01/mcpulse:latest
    container_name: mcpulse-server
    volumes:
      - ./config.yaml:/app/config.yaml
    ports:
      - "8080:8080"  # Web UI and API
      - "9090:9090"  # gRPC endpoint
    environment:
      DATABASE_URL: postgres://mcp_user:changeme@timescaledb:5432/mcp_analytics?sslmode=disable
      JWT_SECRET: your_jwt_secret_here_at_least_32_chars  # Change this!
    depends_on:
      - timescaledb

volumes:
  mcpulse-data:

Important: Change the POSTGRES_PASSWORD and JWT_SECRET values before running!

Step 3: Start Services​

docker compose up -d

This will start:

Step 4: Verify Installation​

Check that all services are running:

docker compose ps

You should see:

NAME                COMMAND                  STATUS
mcpulse-server      "/app/mcpulse"          Up
mcpulse-timescale   "docker-entrypoint..."  Up

Step 5: Create an API Key​

  1. Visit http://localhost:8080
  2. Create an account or log in
  3. Go to API Keys
  4. Click Create API Key
  5. Copy the generated key (you'll need it for SDK integration)

Building from Source​

If you want to build MCPulse from source for development or customization:

Step 1: Clone the Repository​

git clone https://github.com/sirrobot01/mcpulse.git
cd mcpulse

Step 2: Configure Environment​

Create environment files from templates:

cp .env.example .env
cp config.yaml.example config.yaml

Edit .env and set your passwords:

# Database
POSTGRES_PASSWORD=your_secure_password_here

# MCPulse JWT Secret (for authentication)
JWT_SECRET=your_jwt_secret_here_at_least_32_chars

Step 3: Build and Start Services​

docker compose up -d

This will build the MCPulse image from source and start all services.

Manual Installation​

For development or custom deployments without Docker, you can install MCPulse manually.

Step 1: Install TimescaleDB​

Using Docker​

docker run -d \
  --name mcpulse-timescale \
  -e POSTGRES_DB=mcp_analytics \
  -e POSTGRES_USER=mcp_user \
  -e POSTGRES_PASSWORD=changeme \
  -p 5432:5432 \
  timescale/timescaledb:latest-pg16

Using Package Manager​

macOS (Homebrew):

brew install timescaledb

Ubuntu/Debian:

sudo apt-get install postgresql-16-timescaledb

Step 2: Setup Frontend​

cd web
npm install
npm run build # This will build the frontend into the correct directory

Step 3: Build MCPulse Server​

# Clone the repository
git clone https://github.com/sirrobot01/mcpulse.git
cd mcpulse

# Build the server
go build -o mcpulse ./cmd/mcpulse

# Create configuration
cp config.yaml.example config.yaml
# Edit config.yaml with your database credentials

Step 4: Run the Server​

./mcpulse --config config.yaml

The server will start on http://localhost:8080 (default).

Verification​

Health Check​

Check if the server is healthy:

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0"
}

Prometheus Metrics​

View Prometheus metrics:

curl http://localhost:8081/metrics

Test Ingestion​

Send a test metric:

curl -X POST http://localhost:8080/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "metrics": [{
      "id": "test-1",
      "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
      "server_id": "test-server",
      "tool_name": "test_tool",
      "duration_ms": 42,
      "status": "success"
    }]
  }'

Expected response:

{
  "accepted": 1,
  "rejected": 0
}

Next Steps​

Now that MCPulse is running:

  1. Integrate an SDK - Choose your language and add MCPulse to your MCP server
  2. Configure - Customize MCPulse for your needs

Troubleshooting​

Database Connection Failed​

If you see database connection errors:

  1. Verify TimescaleDB is running:

    docker ps | grep timescale
    # or
    pg_isready -h localhost -p 5432

  2. Check credentials in config.yaml or .env

  3. Verify network connectivity:

    psql -h localhost -U mcp_user -d mcp_analytics

Port Already in Use​

If port 8080 is already in use:

  1. Docker Compose: Edit docker compose.yml and change the port mapping
  2. Manual: Edit config.yaml and set a different port: 
    server:
      port: 9000

Additional Resources​