perdoo

This MCP server provides a focused integration with the Perdoo OKR platform via its GraphQL API. It exposes 19 tools organized into categories for managing objectives, key results, initiatives, KPIs, and strategic pillars, along with helper tooling to look up timeframes, users, and groups. You can interact with the MCP using the /mcp endpoint over HTTP; the server streams updates via SSE on GET /mcp, and supports session-based transport for long-running interactions. To start using it locally, configure your Perdoo API token and run the server; then call the individual tool endpoints through the MCP client by addressing the perdoo MCP server you defined (e.g., http://localhost:3001/mcp). Each tool corresponds to a Perdoo operation (list, get, create, update) across the major entities: objectives, key results, initiatives, KPIs, and strategic pillars, plus helper tools like list_timeframes, list_users, and list_groups for contextual data during your operations.

Prerequisites:

• Node.js >= 18
• npm (comes with Node.js)

Install and run locally:

1. Clone the repository git clone https://github.com/nevilhulspas/perdoo-mcp.git
2. Navigate to the project cd perdoo-mcp
3. Install dependencies npm install
4. Create and configure environment cp .env.example .env Edit .env and set PERDOO_API_TOKEN to your Perdoo API token
5. Build and start the server npm run build npm start

If you prefer Docker:

1. Build the Docker image npm run docker:build
2. Run the container npm run docker:run

The server will listen on port 3001 by default (adjust via PORT in the environment).

Security and deployment tips:

• The MCP endpoint does not include authentication by default. For production, enable authentication by adding a shared-secret middleware or leveraging reverse-proxy authentication (e.g., Traefik BasicAuth). See the README's Authentication section for guidance.
• Sessions are stored in memory. In containerized deployments, expect session loss on restart; this is by design for the Streamable HTTP transport used by MCP.
• The resilience stack (request queue, circuit breaker, retries, rate limiting) helps protect the Perdoo API and maintain stable MCP interactions.
• If deploying remotely, ensure environment variables like PERDOO_API_TOKEN and PORT are securely provided to the container or hosting platform.
• Health checks: use GET /health to verify status, version, and active sessions.
• For production, consider enabling IP allowlisting or API key middleware to restrict access to known clients.