PIM MCP Server

MCP server (stdio transport) that wraps the PIM Gateway REST API into typed MCP tools. Provides email, calendar, and task management capabilities to AI agents.

Prerequisites

• Node.js 20+
• PIM Gateway running behind Kong
• Authentik OAuth2 credentials

Installation

From npm

npm install -g pim-mcp-server

Or run directly with npx:

npx pim-mcp-server

From source

cd pim-mcp-server
npm install
npm run build

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | PIM_AUTHENTIK_URL | Yes | — | Authentik URL (e.g. https://argus:9443) | | PIM_KONG_URL | Yes | — | Kong proxy URL (e.g. https://argus:8443) | | PIM_CLIENT_ID | No | pim-gateway | OAuth2 client ID | | PIM_CLIENT_SECRET | Yes | — | OAuth2 client secret |

Available Tools (24)

Email (9)

| Tool | Description | |---|---| | pim_list_emails | List emails from a Gmail label | | pim_search_emails | Search emails using Gmail query syntax | | pim_get_email | Get full email content | | pim_send_email | Send a new email | | pim_reply_email | Reply to an email | | pim_list_attachments | List email attachments | | pim_download_attachment | Download an attachment | | pim_trash_email | Trash an email (admin) | | pim_delete_email | Permanently delete (admin) |

Calendar (5)

| Tool | Description | |---|---| | pim_list_events | List events in a time range | | pim_get_event | Get event details | | pim_create_event | Create a new event | | pim_update_event | Update an event | | pim_delete_event | Delete an event (admin) |

Tasks (7)

| Tool | Description | |---|---| | pim_list_task_lists | List all task lists | | pim_list_tasks | List tasks in a list | | pim_get_task | Get task details | | pim_create_task | Create a new task | | pim_update_task | Update a task | | pim_complete_task | Mark task complete | | pim_delete_task | Delete a task (admin) |

Health & Admin (3)

| Tool | Description | |---|---| | pim_health | Liveness check | | pim_health_ready | Readiness check (DB + Google API) | | pim_audit_log | Query audit log (admin) |

Client Configuration

Claude Code

Add to .claude/settings.json or project settings.json:

{
  "mcpServers": {
    "pim": {
      "command": "npx",
      "args": ["pim-mcp-server"],
      "env": {
        "PIM_AUTHENTIK_URL": "https://argus:9443",
        "PIM_KONG_URL": "https://argus:8443",
        "PIM_CLIENT_SECRET": "<your-secret>"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pim": {
      "command": "npx",
      "args": ["pim-mcp-server"],
      "env": {
        "PIM_AUTHENTIK_URL": "https://argus:9443",
        "PIM_KONG_URL": "https://argus:8443",
        "PIM_CLIENT_SECRET": "<your-secret>"
      }
    }
  }
}

OpenClaw (on Jarvis)

export PIM_AUTHENTIK_URL=https://argus:9443
export PIM_KONG_URL=https://argus:8443
export PIM_CLIENT_SECRET=<your-secret>
npx pim-mcp-server

Testing

Run the smoke test to verify connectivity:

PIM_AUTHENTIK_URL=https://argus:9443 \
PIM_KONG_URL=https://argus:8443 \
PIM_CLIENT_SECRET=<your-secret> \
npm test

Building & Publishing

Build

npm run build    # compiles TypeScript to dist/

Publish to npm

Requires npm login with 2FA:

npm login
npm publish --otp=<2fa-code>

To publish a new version:

npm version patch   # or minor, major
npm publish --otp=<2fa-code>

Design

• Role-agnostic: All endpoints are exposed. RBAC is enforced by the PIM Gateway, not this server. The same binary serves OpenClaw (agent role) and Claude Desktop (admin role) — only the credentials differ.
• Auth caching: JWT tokens are cached in memory and auto-refreshed 30 seconds before expiry. On 401, the token is force-refreshed and the request retried once.
• Full envelope: Tool responses return the complete PIM Gateway response envelope (status, data, error, meta) for debugging and traceability.
• Logging: Token refreshes and API calls (method, path, status, duration) are logged to stderr.