PeopleSoft MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to query and understand PeopleSoft HCM databases. This server provides semantic tools for HR, Payroll, Benefits, Performance, and PeopleTools metadata - allowing natural language questions to be answered with accurate SQL queries.

Features

• 41 semantic tools covering all major PeopleSoft HCM modules

• 4 documentation resources for PeopleSoft concepts and query patterns

• Direct database access via Oracle thin client (no JDBC required)

• PeopleTools introspection for understanding system architecture

• Effective dating support built into all queries

Quick Start

Prerequisites

• Python 3.11+

• Oracle Database connectivity to a PeopleSoft HCM 9.2 instance

• uv package manager (recommended)

Installation

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

# Install dependencies
uv sync

Configuration

1. Copy the example environment file and add your credentials:

cp .env.example .env

2. Edit .env with your database credentials:

ORACLE_DSN=hostname:port/service_name
ORACLE_USER=your_username
ORACLE_PASSWORD=your_password

3. Edit .cursor/mcp.json and update the path to your installation.

Running the Server

uv run peoplesoft_server.py

Cursor IDE Integration

The MCP config (.cursor/mcp.json) should look like:

{
  "mcpServers": {
    "peoplesoft": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp_ps/",
        "run",
        "peoplesoft_server.py"
      ]
    }
  }
}

Credentials are loaded from .env automatically - no need to include them in the MCP config.

Available Tools

Schema Introspection (5 tools)

HR Module (5 tools)

Payroll Module (5 tools)

Benefits Module (4 tools)

Performance Module (3 tools)

PeopleTools Module (18 tools)

Direct Query (1 tool)

Available Resources

Project Structure

peoplesoft-mcp/
├── peoplesoft_server.py    # Main MCP server entry point
├── db.py                   # Database connection management
├── tools/                  # Semantic tool modules
│   ├── introspection.py    # Schema discovery tools
│   ├── hr.py               # HR module tools
│   ├── payroll.py          # Payroll module tools
│   ├── benefits.py         # Benefits module tools
│   ├── performance.py      # ePerformance tools
│   └── peopletools.py      # PeopleTools metadata tools
├── tests/                  # Test suites
│   ├── test_business_questions.py   # HR business scenarios
│   └── test_peopletools_questions.py # Technical consultant scenarios
├── docs/                   # Documentation resources
│   ├── peoplesoft_concepts.md
│   ├── peoplesoft_schema_guide.md
│   ├── peopletools_guide.md
│   ├── sql_query_examples.md
│   ├── peopletools-tables-by-tool.md   # Tables required per tool
│   └── migration-analysis.md   # Migration planning notes
└── pyproject.toml          # Project configuration

Running Tests

# Set environment variables
export ORACLE_DSN="hostname:port/service_name"
export ORACLE_USER="username"
export ORACLE_PASSWORD="password"

# Run all tests
uv run pytest tests/ -v -s

# Run specific test suite
uv run pytest tests/test_business_questions.py -v -s
uv run pytest tests/test_peopletools_questions.py -v -s

Example Queries

The MCP enables natural language questions like:

Business Questions:

• "How many active employees are in each company?"

• "What is the average salary by department?"

• "Who reports to manager X?"

• "Show me employees without a supervisor assigned"

Technical Questions:

• "What fields does PS_JOB have?"

• "Where is the DEPTID field used?"

• "What PeopleCode runs on the JOB record?"

• "What SQL does HR_ABSV_JOB_EFFDT use?"

• "Search for SQL objects referencing PS_ABSV_REQUEST"

• "Explain effective dating in PeopleSoft"

Development

Adding New Tools

1. Create a new module in tools/ or add to existing module

2. Define async functions that use db.execute_query()

3. Add a register_tools(mcp) function

4. Import and register in peoplesoft_server.py

Key Concepts

• Effective Dating: Most PeopleSoft tables use EFFDT/EFFSEQ for history

• SetID: Controls data sharing across business units

• Translate Values: Short codes decoded via PSXLATITEM

• EMPLID/EMPL_RCD: Employee ID + employment record number

License

MIT

Changelog

v0.2.1 (2026-03-02)

• Added get_sql_definition - fetch SQL text by SQLID from PSSQLTEXTDEFN

• Added search_sql_definitions - search SQL objects by text

• PeopleTools compatibility: adjusted PSPNLGROUP, PSPNLFIELD, PSAEAPPLDEFN, PSAESTEPDEFN queries for varying column names across PeopleTools versions

• Added docs/peopletools-tables-by-tool.md - tables required per tool

v0.2.0 (2026-02-28)

• Added modular tool architecture with 39 semantic tools

• Added PeopleTools introspection module (16 tools)

• Added comprehensive test suites (42 tests)

• Replaced connection pooling with direct connections for reliability

• Added 4 documentation resources

• Improved effective dating patterns in all queries