Planview Portfolios Actions MCP Server

Planview Portfolios MCP Server

An MCP server that connects Planview Portfolios (enterprise strategic portfolio management) to Claude Desktop or any MCP-compatible AI client. 24 tools covering projects, tasks, financial plans, OKRs, and work hierarchy — bridging both REST and legacy SOAP APIs under a single MCP interface.

Why This Exists

Planview Portfolios is an enterprise SPM platform used by large organizations to manage project portfolios, resource capacity, and strategic funding. Its API surface is split across REST (projects, work items, OKRs) and SOAP (tasks, financial plans) with different auth models and data formats.

I built this server to unify both API layers behind MCP so Claude can create projects, build financial plans, manage OKRs, and navigate work hierarchies through conversation. It's the write/action companion to Planview's own read-only Beta MCP server — together they cover the full platform.

This is the second MCP server I built for Planview products (the first was AgilePlace MCP Server). Same pattern, completely different APIs — AgilePlace is a modern REST API, Portfolios mixes REST with SOAP services that require different serialization, auth, and error handling.

What It Does

• Projects — full CRUD, attribute discovery, WBS tree navigation
• Tasks (SOAP) — create, read, delete, batch operations via Planview's TaskService
• Financial Plans (SOAP) — read, upsert, discover structure, copy from reference projects
• OKRs — list objectives, key results, bulk fetch
• Work Hierarchy — list, read, and update work items across the portfolio tree
• Two-server architecture — designed to run alongside Planview's hosted Beta MCP, with routing hints so Claude knows which server handles each request

Tech Stack

• Runtime: Python 3.10+
• Protocol: MCP over stdio (official mcp Python SDK)
• APIs: Planview REST (OAuth2) + SOAP (zeep) — TaskService, FinancialPlanService
• Validation: Pydantic for config and input models
• HTTP: httpx (REST), zeep (SOAP)

Architecture

Claude Desktop / MCP Client
        ↓ stdio
  Local MCP Server (Python)
    ├── Planview REST API (OAuth2 client credentials)
    │     ├── Projects
    │     ├── Work Items
    │     └── OKRs
    └── Planview SOAP API (zeep + OAuth2)
          ├── TaskService
          └── FinancialPlanService

  + Planview Beta MCP (remote, read-only)
    └── Portfolios, search, cross-tabs, strategies, resources
## Two-Server Architecture

This server is designed to run **alongside** the Planview-hosted Beta MCP (`Planview Portfolios US`). Together they cover the full Portfolios surface:

| Server | Role | Tools | Transport |
| --- | --- | --- | --- |
| **Beta MCP** (`Planview Portfolios US`) | Read — portfolios, search, cross-tabs, strategies, resources, dependencies, hierarchy trees | 29 | Planview-hosted (remote) |
| **Local MCP** (`planview-portfolios-actions`) | Write — create/update/delete projects, SOAP tasks, financial plans, OKRs, work node access | 24 | Local stdio |

**Beta handles:** "Show me my portfolios," "List projects in Mobility," "How many projects are in-flight?," "Search for a project by name," "What's the strategy breakdown?"

**Local handles:** "Create a new project," "Add tasks to this project," "Set up a financial plan," "Show me OKRs," "Update project status," "Copy a financial plan from a reference project."

**Together:** Beta finds → Local acts. "Find all behind-schedule projects in Mobility" (beta) → "Update their status to At Risk" (local).

All tool descriptions include `[LOCAL — ...]` routing hints so Claude knows which server to use without guessing.

## Before You Start — Checklist

Gather these **before** you touch anything. You will be stuck without them.

- [ ] **API URL** — Your Planview instance URL + `/polaris` (e.g., `https://scdemo5xx.pvcloud.com/polaris`) — must be **lowercase**
- [ ] **Client ID** — From Administration → Users → OAuth2 credentials
- [ ] **Client Secret** — Shown **once** at OAuth credential creation. If you didn't copy it, you need to create a new one.
- [ ] **Global Tenant ID** — This is not obvious in the UI. Ask your Planview admin.

> ⚠️ **Do not skip this step.** You will get through the entire setup and hit a wall at the end if any of these are missing or wrong.

---

## Setup — Windows

### Step 1: Install Python

If you've never installed Python before, that's fine. Go to [python.org/downloads](https://www.python.org/downloads/) and download the latest version.

When the installer opens, you'll see a checkbox at the bottom that says **"Add Python to PATH"**. **Check that box.** This is the most important part of the install.

After it finishes, **close any open Command Prompt windows** and open a fresh one:

1. Press the **Windows key**, type `cmd`, press **Enter**
2. Type these two commands, one at a time:

python --version pip --version ```

You should see version numbers for both. If you see "not recognized," go back and reinstall Python with the PATH checkbox checked.

Step 2: Download this repository

1. On the GitHub page, click the green Code button → Download ZIP
2. Extract the zip to C:\portfoliosMCP

⚠️ Use a simple path like C:\portfoliosMCP. Do NOT put this in OneDrive, your Desktop, or any folder with spaces in the name. It will cause problems later.

⚠️ Check for a folder-inside-a-folder. After unzipping, open C:\portfoliosMCP. If you see another folder called portfoliosMCP-main instead of files like pyproject.toml, move everything up one level so pyproject.toml sits directly inside C:\portfoliosMCP.

Step 3: Install the server

1. Open Command Prompt (Windows key → type cmd → Enter)
2. Run these commands one at a time:

cd C:\portfoliosMCP
python -m venv venv
venv\Scripts\activate
pip install -e .

Wait for each command to finish before running the next one. The last command will download dependencies and may take a minute or two.

ℹ️ What does this do? It creates an isolated Python environment (venv) and installs the server into it. You must use pip install -e . — running pip install -r requirements.txt alone is not enough and the server will fail to start.

Step 4: Get your Python path

While still in Command Prompt, run:

where python

Copy the line that includes venv\Scripts\python.exe. It should look something like:

C:\portfoliosMCP\venv\Scripts\python.exe

You'll need this in the next step.

Step 5: Configure Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Developer → Edit Config

Or: press Win+R, type %APPDATA%\Claude, press Enter, and open claude_desktop_config.json in Notepad.

If the file doesn't exist, create a new text file with that exact name.

Step 6: Paste this into the config file

{
  "mcpServers": {
    "planview-portfolios-actions": {
      "command": "C:\\portfoliosMCP\\venv\\Scripts\\python.exe",
      "args": ["-m", "planview_portfolios_mcp"],
      "env": {
        "PLANVIEW_API_URL": "https://your-instance.pvcloud.com/polaris",
        "PLANVIEW_CLIENT_ID": "your_client_id",
        "PLANVIEW_CLIENT_SECRET": "your_client_secret",
        "PLANVIEW_TENANT_ID": "your_tenant_id",
        "USE_OAUTH": "true"
      }
    }
  }
}

Replace:

• The command path with your output from Step 4
• All four your_... values with your actual Planview credentials from the checklist

Two critical rules for this file:

1. Double every backslash in the path. C:\portfoliosMCP must be written as C:\\portfoliosMCP. If you don't, you'll get a "Bad escaped character" error and Claude Desktop won't start properly.
2. API URL must be lowercase. https://scdemo508.pvcloud.com/polaris — not SCDEMO508. Uppercase can cause authentication failures.

Step 7: Restart Claude Desktop

Close Claude Desktop completely — use File → Exit or right-click the icon in the system tray and quit. Just clicking the X may not fully close it. Then reopen it.

Step 8: Test it

In Claude Desktop, type:

Use oauth_ping to check my Planview connection

If you see a success response, you're done. If you get an error, check the troubleshooting table below.

---

Setup — macOS

Step 1: Install Python

brew install python3

Step 2: Clone and install

git clone https://github.com/norman2112/portfoliosMCP.git
cd portfoliosMCP
python3 -m venv venv
source venv/bin/activate
pip install -e .

Step 3: Get your Python path

which python3
# Example output: /Users/yourname/portfoliosMCP/venv/bin/python3

Step 4: Open the Claude Desktop config file

# Press Cmd+Shift+G in Finder and paste this path:
~/Library/Application Support/Claude/claude_desktop_config.json

# Or from terminal:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

If the file doesn't exist, create it.

Step 5: Paste the config

{
  "mcpServers": {
    "planview-portfolios-actions": {
      "command": "/Users/yourname/portfoliosMCP/venv/bin/python3",
      "args": ["-m", "planview_portfolios_mcp"],
      "env": {
        "PLANVIEW_API_URL": "https://your-instance.pvcloud.com/polaris",
        "PLANVIEW_CLIENT_ID": "your_client_id",
        "PLANVIEW_CLIENT_SECRET": "your_client_secret",
        "PLANVIEW_TENANT_ID": "your_tenant_id",
        "USE_OAUTH": "true"
      }
    }
  }
}

Replace the Python path with your output from Step 3. Fill in all four credential values.

Step 6: Quit Claude Desktop (Cmd+Q) and reopen it.

Step 7: Test it

Ask Claude: "Use oauth_ping to check my Planview connection"

---

Troubleshooting

| What you see | What's wrong | How to fix it | |---|---|---| | python or pip is "not recognized" | Python isn't installed or isn't on PATH | Reinstall Python from python.org — check "Add Python to PATH" | | "Bad escaped character in JSON" | Single backslashes in the config file | Change every \ to \\ in the command path | | "No module named planview_portfolios_mcp" | Package not installed into the venv | Run pip install -e . from the repo folder (not pip install -r requirements.txt) | | OAuth 400 error | Bad credentials or uppercase API URL | Double-check all four credential values. Make sure the API URL is lowercase and ends with /polaris | | 401 Unauthorized | Wrong Client ID, Secret, or Tenant ID | Re-verify all credentials. Watch for extra spaces when pasting | | Tools don't show up in Claude | Claude Desktop didn't fully restart | Quit via File → Exit (not just X), then reopen | | JSON syntax error on startup | Malformed config file | Copy your config into jsonlint.com to find the error | | Folder has no pyproject.toml | Nested folder from GitHub zip | Look one folder deeper — move contents up so pyproject.toml is at your root path |

---

Getting Your Planview Credentials

1. Log into Planview as admin → Administration → Users → OAuth2 credentials tab
2. Click Create OAuth2 credentials
3. Name it (e.g., "MCP Server"), select Portfolios Integration
4. Copy the Client ID and Client Secret (⚠️ secret is only shown once)
5. Find your Tenant ID in the admin panel or ask your Planview admin

---

Tools

These sections list every MCP tool this server registers (24 total). Older drafts of this project mentioned list_resources / get_resource / allocate_resource; those helpers still exist in tools/resources.py as optional, non-exposed REST wrappers—they are not in tool_registry.py or server.py and clients will not see them.

Projects (REST) — Read & Write

| Tool | Description | | --- | --- | | get_project | Get a single project by ID | | create_project | Create a new project (auto-defaults dates if omitted) | | update_project | Partial update of project fields | | delete_project | Delete a project by ID (destructive — removes project and all child data) | | get_project_attributes | List available project attributes | | get_project_wbs | Get project WBS as a nested tree | | list_field_reference | Browse writable fields by category (for create/update) |

For listing/searching projects across portfolios, use Beta MCP's listProjectsByPortfolioId, searchProjectByName, or getProjectsByPortfolioId.

Work Items (REST) — Read & Write

| Tool | Description | | --- | --- | | list_work | List work items using a filter string (e.g., project.Id .eq 1906) | | get_work | Get a single work/hierarchy node by ID (including portfolio-level nodes) | | update_work | Partial update of a work item | | get_work_attributes | List available work attributes |

For portfolio-scoped project lists, use Beta MCP's listProjectsByPortfolioId.

Tasks (SOAP) — Write-Only

| Tool | Description | | --- | --- | | create_task | Create a task (PascalCase fields, key URI format) | | read_task | Read a task by key (key://, ekey://, or search://) | | delete_task | Delete a task (cascades to children) | | batch_create_tasks | Create multiple tasks in a single SOAP call | | batch_delete_tasks | Delete multiple tasks (returns per-key success/failure) |

Task updates are not exposed: the SOAP Update operation does not serialize reliably with zeep. To change a task, delete and recreate it (or use the Planview UI).

For reading tasks with custom attributes, Beta MCP's getTasksByProjectIds or getTasksByTaskIds may be richer.

Financial Plans (SOAP) — Local-Only

| Tool | Description | | --- | --- | | read_financial_plan | Read plan structure, accounts, and periods | | upsert_financial_plan | Create or update a financial plan (single-line optimized) | | discover_financial_plan_info | Smart discovery with reference project fallback | | load_financial_plan_from_reference | Copy account structure + values from a reference project (dry-run by default) |

Tip: Use discover_financial_plan_info or read_financial_plan first to find valid account/period keys before calling upsert_financial_plan.

No Beta MCP equivalent exists for financial plans.

OKRs (REST) — Local-Only

| Tool | Description | | --- | --- | | list_objectives | List objectives with pagination | | get_key_results_for_objective | Get key results for a specific objective | | list_all_objectives_with_key_results | Bulk fetch all objectives + their key results |

No Beta MCP equivalent exists for OKRs.

Utility

| Tool | Description | | --- | --- | | oauth_ping | Verify OAuth credentials are working |

Authentication

| Variable | Description | | --- | --- | | PLANVIEW_API_URL | Base URL including /polaris path (lowercase) | | PLANVIEW_CLIENT_ID | OAuth Client ID | | PLANVIEW_CLIENT_SECRET | OAuth Client Secret | | PLANVIEW_TENANT_ID | Organization Tenant ID |

The Client Secret is only shown once at creation. Store it securely.

SOAP API Notes

This server uses both REST and SOAP APIs. SOAP is used for tasks (TaskService) and financial plans (FinancialPlanService).

Key things to know:

• Response payloads may be incomplete — the API confirms success but doesn't always echo back full data. Use the corresponding read tool to verify.
• Warnings are non-fatal — InvalidStructureCode and InvalidDefaultValues indicate configuration issues but don't prevent successful operations.
• Field names are PascalCase — FatherKey, not father_key.
• Key URI formats: key://2/$Plan/12345 (direct), ekey://2/namespace/id (external), search://2/$Plan?description=Name (search).
• batch_delete_tasks has known SOAP response parsing reliability issues — verify deletions with read_task.

See SOAP_API_BEHAVIORS.md for the full rundown.

Known Limitations

• list_projects without a filter — some instances require a filter (e.g., project.Id .eq 3817)
• update_work — returns 405 on some instances. Use update_project for project-level items
• Task updates — not supported. Workaround: delete + recreate
• batch_delete_tasks — SOAP response parsing is flaky. Verify with read_task

Development

python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env  # Add your credentials

# Run
python -m planview_portfolios_mcp
planview-portfolios-actions   # console script (same server; MCP name planview-portfolios-actions)

# Test & lint
pytest
black src/ && ruff check src/ && mypy src/

Project Structure

src/planview_portfolios_mcp/
├── server.py          # MCP Server (stdio) + tool routing
├── tool_registry.py   # Tool definitions, routing hints, input schemas
├── __main__.py        # Entry point (python -m planview_portfolios_mcp)
├── config.py          # Pydantic Settings (loads from .env)
├── client.py          # Shared HTTP client with retry logic
├── soap_client.py     # SOAP client (zeep) with retry logic
├── exceptions.py      # Custom exception hierarchy
├── models.py          # Pydantic input validation models
├── logging_config.py  # Structured logging
└── tools/
    ├── projects.py    # Project tools
    ├── work.py        # Work hierarchy tools
    ├── tasks.py       # Task tools (SOAP)
    ├── financial_plan.py  # Financial plan tools (SOAP)
    ├── okrs.py        # OKR tools
    ├── ping.py        # OAuth ping
    ├── resources.py   # Internal REST helpers for /resources (not MCP-exposed)
    └── __init__.py

Requirements

• Python 3.10+
• Planview Portfolios instance with OAuth API access
• mcp>=1.0.0 for MCP SDK (stdio transport)
• httpx for REST, zeep for SOAP — see pyproject.toml

License

MIT