Planview MCP Server

MCP server for Planview Enterprise One with Okta passwordless authentication and automated timesheet completion.

What This Does

• 🔐 Authenticate to Planview using Okta Verify (no passwords)
• 📊 Access Planview API (work items, projects, users)
• 🤖 Auto-complete timesheets with /complete-timesheets command

Quick Start

Step 1: Clone and Install

git clone <your-repo-url>
cd planview-mcp
npm install
npx playwright install chromium

Step 2: Configure

Linux/macOS:

cp .mcp.json.example .mcp.json
nano .mcp.json  # or use any text editor

Windows:

copy .mcp.json.windows.example .mcp.json
notepad .mcp.json  # or use any text editor

Edit the env section in .mcp.json with your Planview details:

• PLANVIEW_BASE_URL: Your company's Planview URL
• OKTA_USERNAME: Your email address

Step 3: Authenticate

npm run okta-login

This opens a browser and waits for you to approve the Okta Verify notification on your phone.

Step 4: Build and Restart Claude

npm run build

Then restart Claude Code to load the MCP server.

Usage

Available Commands

Command	Description
/complete-timesheets	Auto-fills all overdue timesheets (8h/day, 40h/week)

Available Tools

Use these directly in Claude:

• planview_get_work_items - List work items
• planview_get_projects - List projects
• planview_get_current_user - Get your user info
• planview_update_work_item - Update a work item
• planview_execute_request - Make custom API calls

More Examples

See EXAMPLES.md for detailed usage examples including:

• Timesheet automation workflows
• Work item management
• Custom API requests
• Creating your own commands
• Troubleshooting tips

How It Works

This setup uses two MCP servers:

1. Planview MCP (this repo) - Handles Planview API and authentication
2. Playwright MCP (auto-installed) - Handles browser automation for timesheets

Both are configured in your .mcp.json file. Playwright MCP downloads automatically when Claude starts.

Authentication flow:

1. You run npm run okta-login once
2. Creates planview-auth.json with your session
3. Both MCP servers use this session file
4. Re-authenticate when session expires

Troubleshooting

Problem	Solution
"Authentication error"	Run npm run okta-login
"Can't see browser during login"	Add HEADLESS=true before npm run okta-login
Windows npx warning	Use .mcp.json.windows.example (has cmd /c wrapper)
"Timesheet automation fails"	Check .mcp.json has both planview and playwright servers
"Missing PLANVIEW_BASE_URL"	Check the env section in .mcp.json

Configuration

Local Setup (Recommended)

Use .mcp.json in this repo directory.

Linux/macOS: Uses npx directly

{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Windows: Requires cmd /c wrapper

{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}

Global Setup (All Projects)

Add to Claude Code MCP settings with absolute paths.

Linux/macOS:

{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["/full/path/to/planview-mcp/dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "/full/path/to/planview-mcp/planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\planview-mcp\\dist\\index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "C:\\full\\path\\to\\planview-mcp\\planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}

Why Clone Instead of Direct Install?

This MCP requires cloning because:

• Authentication creates planview-auth.json locally
• Both MCP servers need access to the same auth file
• Each company has different Planview URLs
• Configuration is set in .mcp.json (committed to repo)

Direct GitHub URL installation won't work due to these local file requirements.

Development

npm run dev    # Watch mode (auto-rebuild)
npm run build  # Build once
npm start      # Run server manually

API Documentation

View Planview API docs at: https://yourcompany.pvcloud.com/planview/swagger/index.html

Security

Never commit these files (already in .gitignore):

• .mcp.json - Your configuration with credentials
• planview-auth.json - Your session

License

MIT