Targetprocess MCP Server README

Targetprocess MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to interact with the Targetprocess project management platform through structured tools and natural language workflows.

This server exposes powerful capabilities for querying, creating, and managing Targetprocess entities such as user stories, bugs, tasks, and features.

It acts as a bridge between LLM agents and the Targetprocess API, providing:

• Structured tool-based access
• Semantic, natural-language-driven workflows

Features

• Create standalone bugs or bugs linked to a user story/bug card

• Retrieve TP entities: bugs, user stories, features, releases

• LLM-Friendly Tools

  • Designed for Claude MCP AI agents

Use Cases examples:

• "Show me currently active release"
• "write me test cases based on 145322 tp user story"
• "write detailed test cases based on 145642 bug, format them inside html
  element, create a test plan and add test cases to it"
• "add a comment to 145155 card saying 'test'"
• "write test cases based on 145640 feature"
• "create a bug based on 145637 user story where Add Tile flyout (for a Static Tile) not show"
• "search for a card with 'Text Element' title"

Available tools:

Releases

• get_current_releases — List all current releases (no params needed)
• get_release_bugs — Get bugs for a release (name, optional results)
• get_release_features — Get features for a release (name, optional results)
• get_release_user_stories — Get user stories for a release (name, optional results)
• get_release_user_stories_with_description — Same as above but includes full descriptions (name, withDescription)
• get_release_open_bugs — Get only active/open bugs for a release (name, withDescription, optional results)
• get_release_open_user_stories — Get only active/open user stories for a release (name, withDescription, optional results)

Features

• get_feature_content — Get a Targetprocess Feature by ID, including description, state, and progress (id)
• get_feature_comments — Get comments for a feature by its ID (id, optional results)
• get_feature_user_stories — Get all user stories for a feature by its ID (id)
• get_not_covered_user_stories_in_feature — Get user stories in a feature not yet covered by tests, includes covered field based on "Test Automation" custom field (id)

User Stories

• get_user_story_bugs — Get all bugs linked to a user story by its ID (id)

Tasks

• get_in_progress_tasks_and_bugs — Get all Tasks and Bugs currently in "In Progress" state assigned to a given user (userId)
• create_task — Create a new task linked to a user story (title, userStoryId, optional description)
• list_my_user_stories — List User Stories assigned to the current user, optionally filtered by state (optional state, optional take, optional skip)
• list_my_bugs — List Bugs assigned to the current user, optionally filtered by state (optional state, optional take, optional skip)

Cards — Read

• get_card_current_status — Get EntityState, TeamState, and assigned teams for a card (id, optional resourceType: UserStory | Bug | Feature, default: UserStory)
• get_bug_content — Fetch full content of a bug by ID (id)
• get_user_story_content — Fetch full content of a user story by ID (id)
• get_bug_comments — Get comments on a bug (id, optional results)
• get_user_story_comments — Get comments on a user story (id, optional results)
• get_user_story_test_cases — Fetch the linked test plan and all its test cases (with steps) for a user story (resourceId)
• get_card_relations — Get all relations (Dependency, Blocker, Relation, Link, Duplicate) for a card, with direction and the related card (id)
• get_relation_types — List the relation types available in this instance (id + name); use to find the relationType name for create_card_relation (no params)
• search_tp_cards — Search TP cards by keyword or phrase in description (keyword, optional entityType: UserStories | Bugs, default: UserStories)

Cards — Write

• add_comment — Post a comment to any card (id, comment)
• add_comment_with_user — Post a comment to any card and mention a specific user (id, comment, user object from get_users)
• update_bug — Update an existing bug (id, optional title, optional bugContent, optional origin, optional projectId, optional teamId, optional entityStateId)

  Resolve state name → ID via get_bug_workflows before passing entityStateId

• update_user_story — Update an existing user story (id, optional title, optional description, optional projectId, optional teamId, optional entityStateId)

  Resolve state name → ID via get_user_story_workflows before passing entityStateId

• create_card_relation — Create a relation between two cards (masterId, slaveId, optional relationType name, default: "Depends on")

  The Slave depends on the Master — the Master must be done first relationType is matched by name against this instance's types; resolve exact names via get_relation_types (it's resolved to an ID before the API call, since TP rejects relation types passed by name)

• delete_card_relation — Remove a relation by its relation ID (relationId)

  Get the relationId from get_card_relations first — it's the relation's own ID, not a card ID

• update_user_story_state — Update the sub-state (team assignment entity state) for a user story (id, optional entityStateId, optional teamId, optional teamAssignmentId)

  1. Call get_user_story_content first to find the assigned team and teamAssignmentId
  2. Call get_user_story_workflows to resolve the target state name → entityStateId

• set_business_value — Set the Business Value (Priority) on a User Story, Feature, or Epic (id, entityType: UserStories | Features | Epics, priorityId)

  Resolve priorityId via get_priorities first — do not guess priority IDs

• get_priorities — List the Priority options available in this instance, used to resolve a priority name (e.g. "Must Have") to its ID (no params)
• delete_card — Delete a card by ID; works on Bugs, User Stories, Features, and Epics (id, type: Bug | UserStory | Feature | Epic)

[!NOTE]
projectId and teamId are optional — fall back to TP_PROJECT_ID and TP_TEAM_ID from config

• create_bug_based_on_card — Create a bug linked to an existing user story or bug card (card object with id+type, title, bugContent, optional origin, optional projectId, optional teamId)

[!NOTE]
projectId and teamId are optional — fall back to TP_PROJECT_ID and TP_TEAM_ID from config

• create_user_story — Create a new user story (title, optional description, optional featureId, optional releaseId, optional projectId, optional teamId)

[!NOTE]
projectId and teamId are optional — fall back to TP_PROJECT_ID and TP_TEAM_ID from config

• create_formatted_user_story — Create a new user story with a structured template description in Header → Definitions → Scenarios → Examples Table → Edge Cases → Acceptance Criteria → References → Notes order (title, header object with asA/iWant/soThat, scenarios array with Gherkin steps, acceptanceCriteria array, optional definitions, examplesTable, edgeCases, references, notes, optional featureId, releaseId, projectId, teamId)

[!NOTE]
projectId and teamId are optional — fall back to TP_PROJECT_ID and TP_TEAM_ID from config

• create_epic — Create a new epic (title, optional description, optional releaseId, optional projectId)
• get_epic_content — Get a Targetprocess Epic by ID, including description, state, and progress (id)
• update_epic — Update an epic's title, description, release, or project (id, optional title, optional description, optional releaseId, optional projectId)
• get_epic_features — Get all features belonging to an epic (id)
• create_feature — DEPRECATED, use create_formatted_feature instead for all new features; only call this when you have a fully pre-written HTML description and the user has explicitly opted out of the structured template (title, optional description, optional epicId, optional releaseId, optional projectId, optional teamId)

[!NOTE]
projectId and teamId are optional — fall back to TP_PROJECT_ID and TP_TEAM_ID from config

• create_formatted_feature — Create a new feature with a feature-level TDRE template in Header → Definitions → Scope & Boundaries → Non-Functional Requirements → Cross-Cutting Scenarios → Child Stories → Open Questions/Risks → References → Notes order (title, header object with businessBackground, nonFunctionalRequirements array with area/requirement/status/storyOrOwner, optional definitions, scope, crossCuttingScenarios, childStories, openQuestions, references, notes, optional epicId, releaseId, projectId, teamId)
• update_feature — Update a feature card with data provided from user input; pass only the fields to change (id, optional title, optional description, optional epicId, optional releaseId, optional projectId, optional teamId, optional entityStateId, optional tags, optional teamIterationId)
• create_test_plan — Create a test plan linked to a UserStory, Bug, or Feature (title, resourceId, optional resourceType, optional description/startDate/endDate)

[!NOTE]
requires TP_PROJECT_ID,

Test Case Workflows

• write_test_cases — Fetch a card (UserStory, Bug, or Feature) by ID and trigger the full test case writing workflow: Claude analyzes the card, generates detailed test cases covering happy path, edge cases, and error scenarios, creates a linked test plan via create_test_plan, then calls add_test_cases_to_test_plan. Each test case description contains Preconditions and Test Type as HTML; steps are passed as a structured array (resourceId, optional resourceType)
• add_test_cases_to_test_plan — Add pre-generated test cases to an existing test plan. Each test case has a name, an HTML description (Preconditions and Test Type only), and a steps array of { description, result } objects — steps are created via the TP test step API rather than embedded in the description (testPlanId, testCases array of {name, description, steps})
• get_test_plan_by_id — Get a test plan by ID, including name, plain-text description, state, project, and linked card (id)
• get_test_plan_test_cases_by_id — Get test cases for a test plan by ID, including cases from nested child test plans/containers; returns id, name, plain-text description, and containing test plan metadata, no steps (id)
• get_test_plan_test_cases_with_steps_by_id — Get test cases directly on a test plan by ID, each with its steps (id)
• get_test_case_by_id — Get a single test case by ID, including plain-text description and its steps (id)
• update_test_case_by_id — Update a test case's name and/or description (id, optional name, optional description)
• add_test_case_step_by_id — Add a new step to a test case (testCaseId, description, result)
• update_test_case_step_by_id — Update a test step's description and/or result (id, optional description, optional result)
• delete_test_case_step_by_id — Delete a test step by ID (id)

Processes & Workflows

• get_processes — Get all Targetprocess processes (no params needed)
• get_process_workflows — Get workflows for a specific process (processId)
• get_bug_workflows — Get all bug entity states/workflows for the configured process (no params needed)
• get_user_story_workflows — Get all user story entity states/workflows for the configured process (no params needed)

Projects

• get_projects — Get all Targetprocess projects (no params needed)

Teams

• get_teams — Get all Targetprocess teams returning id and name (no params needed)
• get_teams_and_team_assignments — Get all teams and team assignments (id and name for each) (no params needed)
• get_team_iterations — Get team iterations (sprints), optionally filtered by team; used to resolve a sprint/iteration name to an ID (optional teamId)

User

• get_logged_in_user — Get the currently logged-in user's info (no params needed)
• get_users — Get all Targetprocess users (no params needed)
• get_user_by_id — Get a single Targetprocess user by their ID (id)

Time Tracking

• log_time — Log time spent on a Task, User Story, or Bug (entityId, entityType: Task | UserStory | Bug, hours, optional description, optional date)
• get_my_time_logs — Get recent time log entries submitted by the current user (optional take)

Assignments

• assign_role — Assign a user to a role (e.g. Business Analyst, Developer, QA Engineer) on a TP card (cardId, userId, roleId)
• assign_role_to_feature — Assign a user to a role on all user stories in a feature in one call (featureId, userId, roleId)
• get_assignment_roles — List all available assignment roles with their IDs

Developer Tools

• get_commit_message — Returns a formatted commit message string for a task or bug ID (id, type: task | bug)

  Format for task on a user story: F#<featureId> US#<userStoryId> T#<taskId> <title> Format for bug on a user story: F#<featureId> US#<userStoryId> B#<bugId> <title> Format for standalone bug: B#<bugId> <title>

• get_version — Returns the current version of the MCP server from package.json (no params needed)

Installation

As a Claude Code Plugin

Prerequisites: Claude Code CLI installed, and a Targetprocess account with API access.

1. Get your Targetprocess API token In Targetprocess, go to Settings → Authentication and Security → New Access Token and copy it.

2. Add this repo as a plugin marketplace Run inside Claude Code:

   bashCopy

   /plugin marketplace add SerhiiMaksymiv/targetprocess-mcp-server
   

3. Install the plugin

   bashCopy

   /plugin install targetprocess-mcp
   

4. Fill in the configuration prompts Claude Code will ask for each value in turn:

   Prompt	What to enter
   Targetprocess API Token	The token from step 1 (input is masked)
   Targetprocess Base URL	Your API endpoint, e.g. https://yourcompany.tpondemand.com/api/v1
   Targetprocess Owner ID	Your user ID — leave the default flow, install first and run the get_logged_in_user tool to look it up if you don't know it yet
   Targetprocess Project ID (optional)	Look up via the get_projects tool — press Enter to skip
   Targetprocess Team ID (optional)	Look up via the get_teams tool — press Enter to skip

   Values are stored by Claude Code (the token is kept masked/sensitive) — no manual editing of settings.json needed.

5. Restart Claude Code (or start a new session) so the plugin's MCP server connects with the new config.

6. Verify it's connected

   bashCopy

   /mcp
   

   targetprocess should show as connected. Try asking Claude something like "show me the current active release" to confirm the tools work end to end.

Updating config later: re-run /plugin install targetprocess-mcp (or use /plugin to manage installed plugins) to be re-prompted for values.

Uninstalling:

/plugin uninstall targetprocess-mcp

Local Installation for Development

{

  "mcpServers": {

    "targetprocess": {

      "command": "/Users/xxx/.config/nvm/versions/node/v22.14.0/bin/node",

      "args": [

        "/path/to/repository"

      ],

      "env": {

        "TP_TOKEN": "<your-tp-token>" // Settings -> Authentication and Security -> New Access Token,

        "TP_BASE_URL": "<tp-api-endpoint>",

        "TP_OWNER_ID": "<tp-owner-id>", // your user id

        "TP_PROJECT_ID": "<tp-project-id>"

        "TP_TEAM_ID": "<tp-team-id>"

      }

    }

}

Claude Desktop

[!NOTE] You need to have node and npm installed on your machine.

{

  "mcpServers": {

    "targetprocess": {

      "command": "npx",

      "args": [

        "-y",

        "targetprocess-mcp-server"

      ],

      "env": {

        "TP_TOKEN": "<your-tp-token>" // Settings -> Authentication and Security -> New Access Token,

        "TP_BASE_URL": "<tp-api-endpoint>", // required

        "TP_OWNER_ID": "<tp-owner-id>", // required, your user id

        "TP_PROJECT_ID": "<tp-project-id>", // optional see available tools 

        "TP_TEAM_ID": "<tp-team-id>" // optional see available tools

      }

    }

  },

}

Claude Code

claude mcp add targetprocess -s user \

  -e TP_TOKEN=<your-tp-token> -e TP_BASE_URL=<tp-api-endpoint> -- npx -y targetprocess-mcp-server

Local Development

git clone --recursive https://github.com/SerhiiMaksymiv/targetprocess-mcp-server.git

cd targetprocess-mcp-server



npm install

npm run build

Testing

Tests live in tests/ and use Vitest. All tool handlers are extracted to src/handlers/ and tested with mocked TpClient instances — no network calls are made.

npx vitest run        # run all tests once

npx vitest            # watch mode

Coverage

53 of 64 tools (83%) are covered by unit tests.