Skip to main content
Glama
deenesjakoruzh
BalaGanaparthi

HR System MCP Server

by BalaGanaparthi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

HR 系统 MCP 服务器

这是一个非官方的 MCP 服务器原型，提供具备 Okta 令牌验证功能的 HR 系统功能。仅供评估和测试使用。

📚 文档

完整文档可在 docs/ 文件夹中找到：

Related MCP server: Insperity MCP Server

概览

HR 系统 MCP 服务器提供：

  • ✅ 员工信息查询

  • ✅ 员工目录列表

  • ✅ 薪资信息访问

  • ✅ 休假申请管理

  • ✅ 所有工具调用的 Okta OAuth 2.0 令牌验证

  • ✅ HTTP/NDJSON 流式传输支持 (FastMCP)

  • ✅ 支持 Railway 部署 🚀

身份验证

此服务器对所有工具调用（initialize 除外）进行 Okta 访问令牌验证：

  • 令牌来源：Okta 授权服务器

  • 验证：JWT 签名、过期时间、受众声明

  • 授权请求头：Authorization: Bearer <access_token>

快速入门

# Setup
cp env.example .env
# Edit .env with your Okta credentials

# Install dependencies
pip install -r requirements.txt

# Run in HTTP mode (for Okta MCP Adapter)
python main.py --http 8001

配置

.env (环境变量)

OKTA_DOMAIN=ijtestcustom.oktapreview.com
OKTA_AUTHORIZATION_SERVER_ID=auss2fth0mcIXHzVO1d7
OKTA_AUDIENCE=
OKTA_REQUIRED_SCOPES=
# When true (default), tools/list without auth returns 401. When false, allows unauthenticated tools/list (e.g. for gateway registration).
# PROTECTED_DISCOVERY=true

可用工具

工具

描述

参数

get_employee

通过 ID 获取员工

employee_id: str

list_employees

列出所有员工

无

get_employee_payroll

获取薪资信息

employee_id: str

get_time_off_requests

获取休假申请

employee_id: str (可选)

使用示例

通过 VS Code/Copilot 直接使用

# Endpoint
http://localhost:8001/mcp

# Authorization
Authorization: Bearer <okta_access_token>

通过 Okta MCP 适配器网关使用

# Gateway will:
# 1. Receive request from client
# 2. Validate Okta token
# 3. Forward to HR System MCP
# 4. Attach authorization header

实现细节

  • 框架：FastMCP 3.0.0b1

  • 服务器：Uvicorn (异步 HTTP)

  • 协议：MCP (模型上下文协议)，支持 NDJSON 流式传输

  • 令牌验证：基于 JWKS 的 JWT 验证，包含签名校验

  • 缓存：带有 TTL 的 JWKS 密钥缓存

请求流程

Client Request
    ↓
Authorization Header (Okta token)
    ↓
Initialize (no token needed)
    ↓
tools/list (validate token)
    ↓
tools/call (validate token)
    ↓
Response

🚀 部署选项

Vercel (无服务器)

部署为无服务器函数 - 自动扩缩容，按使用量付费

  • ✅ 适用场景：零星使用，自动缩容至零

  • ✅ 免费层级：100GB 带宽/月

  • ⚠️ 限制：10 秒超时（免费版），5 分钟（Pro 版）

  • 📖 指南：docs/VERCEL_README.md

Railway.com (传统服务器)

部署为长驻服务器 - 始终在线，无超时限制

  • ✅ 适用场景：持续流量，持久连接

  • ✅ 免费层级：500 小时/月（之后为 $5/月）

  • ✅ 无超时：请求持续时间无限制

  • 📖 指南：docs/RAILWAY_README.md

Docker (本地开发)

使用 Docker 本地运行 - 完全控制，便于测试

docker-compose up -d

建议：

  • 对于零星/不可预测的使用场景，请使用 Vercel（更便宜，自动扩缩容）

  • 对于持续流量或需要长超时的场景，请使用 Railway

故障排除

请参阅 docs/RAILWAY_DEPLOYMENT.md 获取完整的故障排除指南。

快速修复：

  • 令牌验证失败：检查 .env 中的 OKTA_DOMAIN 和 OKTA_AUTHORIZATION_SERVER_ID

  • 端口已被占用：在启动命令中更改端口：python main.py --http 8002

  • 缺少环境变量：复制 .env 示例并填入值

  • JWKS 获取错误：验证 Okta 域名和授权服务器 ID 是否正确

项目结构

hr-mcp-server/
├── main.py                    # FastMCP server with HTTP handler
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker container definition
├── docker-compose.yml         # Docker Compose configuration
├── railway.json               # Railway deployment config
├── deploy-railway.sh          # Deployment helper script
├── test_server.sh            # Server test script
├── auth/                      # Authentication module
│   ├── __init__.py
│   └── okta_validator.py     # Okta token validation
└── docs/                      # Documentation
    ├── INDEX.md              # Documentation index
    ├── RAILWAY_README.md     # Railway quick start
    ├── RAILWAY_DEPLOYMENT.md # Complete deployment guide
    ├── DOCKER_QUICK_START.md # Docker reference
    ├── README_INTEGRATION.md # Usage guide
    ├── CLAUDE_CODE_SETUP.md  # Claude Code setup
    ├── CLAUDE.md             # Developer documentation
    └── ...more docs

请参阅 docs/INDEX.md 获取完整的文档指南。

测试

# Using curl with Okta token
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <your_okta_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

📖 文档

如需完整文档，请查看 docs/ 文件夹：

参考资料

状态

⚠️ 非官方原型 - 仅供评估和测试使用。不适用于生产环境。

许可证：Apache 2.0

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Insperity MCP Server

    lwanger
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Insperity's REST API to access employee data, including employee lists, check details, and profile information for HR management tasks.
    -

  • hr-mcp-server

    jyotsnaraghunathan-okta
    F
    license
    Not graded
    quality
    C
    maintenance
    An unofficial prototype MCP server providing HR system functionality with Okta token validation, enabling employee information lookup, directory listing, payroll access, and time-off request management.
    -

  • self-service-mcp

    popuripk
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables workplace self-service tasks such as directory lookup, time-off management, ticket creation, and policy search, with write operations governed and compensation changes structurally denied.
    MIT