mcpctl/docs/getting-started.md

Getting Started with mcpctl

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 9.0.0
• PostgreSQL (for mcpd)
• Docker or Podman (for container management)

Installation

# Clone the repository
git clone <repo-url>
cd mcpctl

# Install dependencies
pnpm install

# Generate Prisma client
pnpm --filter @mcpctl/db exec prisma generate

# Build all packages
pnpm build

Quick Start

1. Start the Database

# Start PostgreSQL via Docker Compose
pnpm db:up

# Run database migrations
pnpm --filter @mcpctl/db exec prisma db push

2. Start the Daemon

cd src/mcpd
pnpm dev

The daemon starts on http://localhost:4444 by default.

3. Use the CLI

# Check daemon status
mcpctl status

# Register an MCP server
mcpctl apply config.yaml

# Or use the interactive wizard
mcpctl setup my-server

# List registered servers
mcpctl get servers

# Start an instance
mcpctl instance start <server-id>

# Check instance status
mcpctl instance list

# View instance logs
mcpctl instance logs <instance-id>

4. Generate .mcp.json for Claude

# Create a project
mcpctl project create my-workspace

# Assign profiles to project
mcpctl project set-profiles <project-id> <profile-id-1> <profile-id-2>

# Generate .mcp.json
mcpctl claude generate <project-id>

# Or manually add servers
mcpctl claude add my-server -c npx -a -y @my/mcp-server

Example Configuration

Create a config.yaml file:

servers:
  - name: slack
    description: Slack MCP server
    transport: STDIO
    packageName: "@anthropic/slack-mcp"
    envTemplate:
      - name: SLACK_TOKEN
        description: Slack bot token
        isSecret: true

  - name: github
    description: GitHub MCP server
    transport: STDIO
    packageName: "@anthropic/github-mcp"

profiles:
  - name: default
    server: slack
    envOverrides:
      SLACK_TOKEN: "xoxb-your-token"

projects:
  - name: dev-workspace
    description: Development workspace

Apply it:

mcpctl apply config.yaml

Running Tests

# Run all tests
pnpm test:run

# Run tests for a specific package
pnpm --filter @mcpctl/cli test:run
pnpm --filter @mcpctl/mcpd test:run
pnpm --filter @mcpctl/local-proxy test:run

# Run tests with coverage
pnpm test:coverage

# Typecheck
pnpm typecheck

# Lint
pnpm lint

Development

# Watch mode for tests
pnpm test

# Build in watch mode
cd src/cli && pnpm dev