freshrelease-mcp 1.4.0

An MCP server for Freshrelease

Freshrelease MCP Server

An MCP server implementation that integrates with Freshrelease, enabling AI models to interact with Freshrelease projects and tasks.

Features

• Freshrelease Integration: Seamless interaction with Freshrelease API endpoints
• AI Model Support: Enables AI models to perform project/task operations through Freshrelease
• Automated Project Management: Handle project and task creation and retrieval

Components

Tools

The server offers several tools for Freshrelease operations:

• fr_create_project: Create a project

  • Inputs: name (string, required), description (string, optional)

• fr_get_project: Get a project by ID or key

  • Inputs: project_identifier (number|string, required)

• fr_create_task: Create a task under a project

  • Inputs: project_identifier (number|string, required), title (string, required), description (string, optional), assignee_id (number, optional), status (string|enum, optional), due_date (YYYY-MM-DD, optional), issue_type_name (string, optional, defaults to "task"), user (string email or name, optional), additional_fields (object, optional)
  • Notes: user resolves to assignee_id via users search if assignee_id not provided. issue_type_name resolves to issue_type_id. additional_fields allows passing arbitrary extra fields supported by your Freshrelease account. Core fields (title, description, assignee_id, status, due_date, issue_type_id) cannot be overridden.

• fr_get_task: Get a task by key or ID within a project

  • Inputs: project_identifier (number|string, required), key (number|string, required)

• fr_get_all_tasks: List issues for a project

  • Inputs: project_identifier (number|string, required)

• fr_get_issue_type_by_name: Resolve an issue type object by name

  • Inputs: project_identifier (number|string, required), issue_type_name (string, required)

• fr_search_users: Search users by name or email within a project

  • Inputs: project_identifier (number|string, required), search_text (string, required)

• fr_link_testcase_issues: Bulk link issues to one or more testcases (using keys)

  • Inputs: project_identifier (number|string, required), testcase_keys (array of string|number), issue_keys (array of string|number)

MCP Tool Reference

<style> .tool-table { width: 100%; border-collapse: collapse; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial; } .tool-table thead th { background: #0f172a; color: #fff; padding: 12px 10px; text-align: left; font-weight: 600; letter-spacing: 0.2px; } .tool-table tbody td { border-top: 1px solid #e5e7eb; vertical-align: top; padding: 12px 10px; } .tool-table tbody tr:nth-child(odd) { background: #f8fafc; } .badge { display: inline-block; padding: 2px 8px; border-radius: 9999px; font-size: 12px; line-height: 18px; margin-right: 6px; background: #e2e8f0; color: #0f172a; } .badge.req { background: #dbeafe; color: #1e3a8a; } .badge.opt { background: #ecfccb; color: #3f6212; } .code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; background: #0b1020; color: #e2e8f0; padding: 2px 6px; border-radius: 6px; } .small { color: #475569; font-size: 12px; } .note { background: #fff7ed; border: 1px solid #fed7aa; padding: 8px 10px; border-radius: 8px; color: #7c2d12; } </style>

Tool	Description	Required Params	Optional Params	Notes
fr_create_project	Create a Freshrelease project	name: string	description: string
fr_get_project	Get a project by id or key	project_identifier: number|string
fr_create_task	Create an issue/task in a project	project_identifier: number|string title: string	description: string assignee_id: number status: string|enum due_date: YYYY-MM-DD issue_type_name: string (defaults to "task") user: string (email or name) additional_fields: object	- If assignee_id not provided and user is, the user is looked up by /{project}/users?q=.. to set assignee_id. - issue_type_name resolves via /{project}/project_issue_types to an issue_type_id. - Protected keys in additional_fields won’t override core fields.
fr_get_task	Get an issue by key or id	project_identifier: number|string key: number|string
fr_get_all_tasks	List all issues in a project	project_identifier: number|string
fr_get_issue_type_by_name	Resolve an issue type object by name	project_identifier: number|string issue_type_name: string
fr_search_users	Search users by name or email	project_identifier: number|string search_text: string		Calls /{project}/users?q=...
fr_link_testcase_issues	Link issues to one or more testcases (by keys)	project_identifier: number|string testcase_keys: array<string|number> issue_keys: array<string|number>		Resolves keys to ids, then calls PUT /{project}/test_cases/update_many.
fr_list_testcases	List all test cases in a project		project_identifier: number|string	Uses FRESHRELEASE_PROJECT_KEY if project_identifier not provided.
fr_get_testcase	Get a specific test case by key or ID	test_case_key: string|number	project_identifier: number|string	Uses FRESHRELEASE_PROJECT_KEY if project_identifier not provided.
fr_get_testcases_by_section	Get test cases in a section and its sub-sections	section_name: string	project_identifier: number|string	Uses FRESHRELEASE_PROJECT_KEY if project_identifier not provided.
fr_add_testcases_to_testrun	Add test cases to a test run	project_identifier: number|string test_run_id: number|string	test_case_keys: array<string|number> section_hierarchy_paths: array<string> section_subtree_ids: array<string|number> section_ids: array<string|number> filter_rule: array<object>	Resolves keys to IDs. section_hierarchy_paths format: "Parent > Child > Grandchild".

For status you may pass a string or enum. Enum values: todo, in_progress, done.

Getting Started

Installing from PyPI

Install the published package directly from PyPI:

pip install -U freshrelease-mcp

Verify installation:

freshrelease-mcp --help

Run the server locally with environment variables:

FRESHRELEASE_API_KEY="<YOUR_FRESHRELEASE_API_KEY>" \
FRESHRELEASE_DOMAIN="<YOUR_FRESHRELEASE_DOMAIN>" \
FRESHRELEASE_PROJECT_KEY="<YOUR_PROJECT_KEY>" \
freshrelease-mcp

Prerequisites

• Freshrelease API access (domain + API key)
• Freshrelease API key

Environment Variables

• FRESHRELEASE_API_KEY: Your Freshrelease API key (required)
• FRESHRELEASE_DOMAIN: Your Freshrelease domain (required)
• FRESHRELEASE_PROJECT_KEY: Default project key/ID to use when not specified in function calls (optional)

Note: When FRESHRELEASE_PROJECT_KEY is set, you can omit the project_identifier parameter from most functions, and the server will automatically use the default project key.

• uvx installed (pip install uv or brew install uv)

Configuration

1. Obtain your Freshrelease API key
2. Set up your Freshrelease domain and authentication details

Usage with Claude Desktop

1. Install Claude Desktop if you haven't already
2. Recommended: Use uvx to fetch and run from PyPI (no install needed). Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "freshrelease-mcp": {
      "command": "uvx",
      "args": [
        "freshrelease-mcp"
      ],
      "env": {
        "FRESHRELEASE_API_KEY": "<YOUR_FRESHRELEASE_API_KEY>",
        "FRESHRELEASE_DOMAIN": "<YOUR_FRESHRELEASE_DOMAIN>"
      }
    }
  }
}

Important Notes:

• Replace <YOUR_FRESHRELEASE_API_KEY> with your Freshrelease API key
• Replace <YOUR_FRESHRELEASE_DOMAIN> with your Freshrelease domain (e.g., yourcompany.freshrelease.com)
• Alternatively, you can install the package and point command directly to freshrelease-mcp.

Usage with Cursor

1. Add the following to Cursor settings JSON (Settings → Features → MCP → Edit JSON):

{
  "mcpServers": {
    "freshrelease-mcp": {
      "command": "uvx",
      "args": [
        "freshrelease-mcp"
      ],
      "env": {
        "FRESHRELEASE_API_KEY": "<YOUR_FRESHRELEASE_API_KEY>",
        "FRESHRELEASE_DOMAIN": "<YOUR_FRESHRELEASE_DOMAIN>"
      }
    }
  }
}

Usage with VS Code (Claude extension)

1. In VS Code settings (JSON), add:

{
  "claude.mcpServers": {
    "freshrelease-mcp": {
      "command": "uvx",
      "args": [
        "freshrelease-mcp"
      ],
      "env": {
        "FRESHRELEASE_API_KEY": "<YOUR_FRESHRELEASE_API_KEY>",
        "FRESHRELEASE_DOMAIN": "<YOUR_FRESHRELEASE_DOMAIN>"
      }
    }
  }
}

Example Operations

Once configured, you can ask Claude to perform operations like:

• "Create a Freshrelease project named 'Roadmap Q4'"
• "Get project 'ENG' details"
• "Create a task 'Add CI pipeline' under project 'ENG' with a custom field"

Example with custom fields for task creation and assignee by email:

{
  "tool": "fr_create_task",
  "args": {
    "project_identifier": "ENG",
    "title": "Add CI pipeline",
    "status": "in_progress",
    "issue_type_name": "task",
    "user": "[e-mail]",
    "additional_fields": {
      "priority": "High",
      "labels": ["devops", "ci"],
      "estimate": 3
    }
  }
}

Link multiple testcases to issues by keys:

{
  "tool": "fr_link_testcase_issues",
  "args": {
    "project_identifier": "ENG",
    "testcase_keys": ["TC-101", "TC-102"],
    "issue_keys": ["ENG-123", "ENG-456"]
  }
}

Testing

For testing purposes, you can start the server manually:

uvx freshrelease-mcp --env FRESHRELEASE_API_KEY=<your_api_key> --env FRESHRELEASE_DOMAIN=<your_domain>

Troubleshooting

• Verify your Freshrelease API key and domain are correct
• Ensure proper network connectivity to Freshrelease servers
• Check API rate limits and quotas
• Verify the uvx command is available in your PATH

License

This MCP server is licensed under the MIT License. See the LICENSE file in the project repository for full details.