niftypm-mcp
cmdaltctr/niftypm-mcp
A Model Context Protocol (MCP) server that exposes the NiftyPM project management API as a set of tools for AI assistants (OpenCode, Claude, Cursor, etc.).
Instalação
npx convez-ai cmdaltctr/niftypm-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
NiftyPM MCP Server
A Model Context Protocol (MCP) server for the NiftyPM project management API.
It lets AI assistants use NiftyPM projects, tasks, documents, files, milestones, messages, labels, portfolios, webhooks, time tracking, custom fields, and related workspace resources through typed MCP tools.
Highlights
- Local
stdioserver for desktop MCP clients. - Optional HTTP stream transport for local testing.
- Cloudflare Workers entry point for hosted/remote use.
- OAuth bearer-token API client with in-memory token refresh on
401. - Zod-validated tool parameters.
- Per-domain tool toggles through
ENABLE_*environment variables, plus per-tool granularity viaDISABLED_TOOLS.
Requirements
- Node.js 20+
- Bun 1.1+
- NiftyPM OAuth credentials:
NIFTYPM_CLIENT_IDNIFTYPM_CLIENT_SECRETNIFTYPM_ACCESS_TOKENNIFTYPM_REFRESH_TOKEN
Install
git clone https://github.com/cmdaltctr/niftypm-mcp.git
cd niftypm-mcp
bun install
Configure
Configurator UI
The easiest setup path is the static configurator at ui/index.html:
- Open
ui/index.htmldirectly in a browser. - Paste your OAuth credentials.
- Switch between Simple (domain-level toggles) and Advanced (per-tool toggle table) tabs.
- Click Download
.env. - Rename it to
.env, place it in the project root, and restart your MCP client.
The configurator runs entirely in your browser. It makes no network requests and does not send secrets anywhere.
The Simple tab shows 20 domain-level switches (core + extended). The
Advanced tab gives you per-tool control — disable individual tools
within an enabled domain, down to a single unwanted operation. The
generated .env is auto-loaded on server start.
Manual .env setup
You can also copy the example env file and fill in your OAuth credentials by hand:
cp .env.example .env
NIFTYPM_CLIENT_ID=your_client_id_here
NIFTYPM_CLIENT_SECRET=your_client_secret_here
NIFTYPM_ACCESS_TOKEN=your_access_token_here
NIFTYPM_REFRESH_TOKEN=your_refresh_token_here
NIFTYPM_REFRESH_TOKEN is the OAuth refresh token for automatic 401 recovery. It is required for stable connections — without it, every access-token expiry forces manual re-authorisation.
How to obtain the refresh token
Use NiftyPM's OAuth authorisation-code flow:
- Create or use a NiftyPM OAuth app and note its client ID, client secret, and redirect URI.
- Open the app's authorisation URL in a browser and approve access.
- Copy the
codevalue from the callback URL sent to your redirect URI. - Exchange that code for tokens with
POST https://openapi.niftypm.com/oauth/token.
Example token exchange:
curl -X POST https://openapi.niftypm.com/oauth/token \
-H "Authorization: Basic $(printf '%s:%s' "$NIFTYPM_CLIENT_ID" "$NIFTYPM_CLIENT_SECRET" | base64)" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE_FROM_CALLBACK",
"redirect_uri": "YOUR_REDIRECT_URI"
}'
The response includes both access_token and refresh_token. Store them as NIFTYPM_ACCESS_TOKEN and NIFTYPM_REFRESH_TOKEN.
Manual .secrets/ option
For OpenCode or local setups, you may store credentials in .secrets/ files instead of .env:
.secrets/client_id
.secrets/client_secret
.secrets/access_token
.secrets/refresh_token
The UI configurator remains the easiest path because it generates a complete .env by copy-paste and download. See Configuration and Deployment for more deployment details.
Run locally
bun run start
Watch mode:
bun run dev
HTTP stream mode:
TRANSPORT=http PORT=8080 bun run start
Deploy to Cloudflare Workers
bun run cf:dev
bun run cf:deploy
Worker access is protected by MCP_AUTH_SECRET. Store production values with wrangler secret put.
Tool domains
The server groups tools by NiftyPM resource domain:
- Projects, portfolios/subteams, members
- Task groups, tasks, subtasks, labels, custom fields
- Documents, files, messages, chat
- Milestones, time tracking, webhooks
- Apps, templates, invite links, current user, auth helpers
For detailed tool names and examples, see Tool Guide.
Project Planning Workflow
The most effective way to populate complex projects is using a JSON-first planning workflow. Instead of making ad-hoc tool calls, define your project structure (milestones, labels, tasks, dependencies) in a JSON file first. This serves as the source of truth, allowing you to validate relationships and ensure tasks have required fields (like story points and real subtasks) before making any API calls to NiftyPM.
For details on executing this four-phase pipeline, see the Workflow Guide.
AI Agent Skills
The SKILLS/ folder contains drop-in agent skill instructions that teach AI coding assistants (Claude Code, OpenCode, Cursor, etc.) how to use this MCP server effectively — including the JSON-first project planning workflow, the four-phase execution pipeline, and NiftyPM best practices.
Copy the SKILLS/s-niftypm/ folder to the appropriate location for your AI client:
| AI Client | Destination path |
|---|---|
| Claude Code | ~/.claude/skills/s-niftypm/ |
| OpenCode | ~/.config/opencode/skills/s-niftypm/ |
| Cursor | ~/.cursor/rules/ (then wrap SKILL.md in a .mdc rule) |
| Other | Check your client's docs for a skills/rules directory |
Example (Claude Code / OpenCode):
# From inside the cloned repo
cp -r SKILLS/s-niftypm ~/.claude/skills/
# or for OpenCode
cp -r SKILLS/s-niftypm ~/.config/opencode/skills/
Once installed, your AI agent will automatically load the s-niftypm skill when working with NiftyPM MCP tools and follow the JSON-first planning workflow by default.
Example tool calls
Create a task:
{
"tool": "niftypm_create_task",
"arguments": {
"name": "Prepare fellowship report",
"task_group_id": "task_group_id_here",
"description": "Draft the report outline."
}
}
Create a related subtask by passing the parent task ID as task_id:
{
"tool": "niftypm_create_task",
"arguments": {
"name": "Collect reviewer feedback",
"task_group_id": "task_group_id_here",
"task_id": "parent_task_id_here"
}
}
Documentation
Development
bun run vitest run
bun run build
Project layout
src/ MCP server, API client, and tool registrations
test/ Vitest tests
docs/guides/ User-facing guides and reference docs
docs/api/ Upstream OpenAPI source files
docs/security/ Security audit notes
Licence
MIT. See LICENSE.