Jira MCP Server

Instructions

Implementation Reference

• src/mcp_server_jira/server.py:1066-1158 (handler)

  Main handler function implementing the create_jira_project tool logic. Calls the JiraV3APIClient to perform the actual project creation.
  async def create_jira_project( self, key: str, name: Optional[str] = None, assignee: Optional[str] = None, ptype: str = "software", template_name: Optional[str] = None, avatarId: Optional[int] = None, issueSecurityScheme: Optional[int] = None, permissionScheme: Optional[int] = None, projectCategory: Optional[int] = None, notificationScheme: Optional[int] = None, categoryId: Optional[int] = None, url: str = "", ) -> JiraProjectResult: """Create a project using Jira's v3 REST API Args: key: Project key (required) - must match Jira project key requirements name: Project name (defaults to key if not provided) assignee: Lead account ID or username ptype: Project type key ('software', 'business', 'service_desk') template_name: Project template key for creating from templates avatarId: ID of the avatar to use for the project issueSecurityScheme: ID of the issue security scheme permissionScheme: ID of the permission scheme projectCategory: ID of the project category notificationScheme: ID of the notification scheme categoryId: Same as projectCategory (alternative parameter) url: URL for project information/documentation Returns: JiraProjectResult with the created project details Note: This method uses Jira's v3 REST API endpoint: POST /rest/api/3/project Example: # Create a basic software project create_jira_project( key='PROJ', name='My Project', ptype='software' ) # Create with template create_jira_project( key='BUSI', name='Business Project', ptype='business', template_name='com.atlassian.jira-core-project-templates:jira-core-simplified-task-tracking' ) """ if not key: raise ValueError("Project key is required") try: # Get the v3 API client v3_client = self._get_v3_api_client() # Create project using v3 API response_data = await v3_client.create_project( key=key, name=name, assignee=assignee, ptype=ptype, template_name=template_name, avatarId=avatarId, issueSecurityScheme=issueSecurityScheme, permissionScheme=permissionScheme, projectCategory=projectCategory, notificationScheme=notificationScheme, categoryId=categoryId, url=url, ) # Extract project details from response project_id = response_data.get("id", "0") project_key = response_data.get("key", key) # For lead information, we would need to make another API call # For now, return None for lead as it's optional in our result model lead = None return JiraProjectResult( key=project_key, name=name or key, id=str(project_id), lead=lead ) except Exception as e: error_msg = str(e) print(f"Error creating project with v3 API: {error_msg}") raise ValueError(f"Error creating project: {error_msg}")
• src/mcp_server_jira/server.py:1507-1529 (registration)

  Tool call dispatcher that maps the tool name 'create_jira_project' to the handler execution.
  case JiraTools.CREATE_PROJECT.value: logger.info("About to AWAIT jira_server.create_jira_project...") key = arguments.get("key") if not key: raise ValueError("Missing required argument: key") # Type conversion logic from original code for int_key in [ "avatarId", "issueSecurityScheme", "permissionScheme", "projectCategory", "notificationScheme", "categoryId", ]: if ( int_key in arguments and isinstance(arguments[int_key], str) and arguments[int_key].isdigit() ): arguments[int_key] = int(arguments[int_key]) result = await jira_server.create_jira_project(**arguments) logger.info("COMPLETED await jira_server.create_jira_project.")
• src/mcp_server_jira/server.py:1341-1398 (schema)

  Registration of the 'create_jira_project' tool including detailed input schema definition.
  Tool( name=JiraTools.CREATE_PROJECT.value, description="Create a new Jira project using v3 REST API", inputSchema={ "type": "object", "properties": { "key": { "type": "string", "description": "Mandatory. Must match Jira project key requirements, usually only 2-10 uppercase characters.", }, "name": { "type": "string", "description": "If not specified it will use the key value.", }, "assignee": { "type": "string", "description": "Lead account ID or username (mapped to leadAccountId in v3 API).", }, "ptype": { "type": "string", "description": "Project type key: 'software', 'business', or 'service_desk'. Defaults to 'software'.", }, "template_name": { "type": "string", "description": "Project template key for creating from templates (mapped to projectTemplateKey in v3 API).", }, "avatarId": { "type": ["integer", "string"], "description": "ID of the avatar to use for the project.", }, "issueSecurityScheme": { "type": ["integer", "string"], "description": "Determines the security scheme to use.", }, "permissionScheme": { "type": ["integer", "string"], "description": "Determines the permission scheme to use.", }, "projectCategory": { "type": ["integer", "string"], "description": "Determines the category the project belongs to.", }, "notificationScheme": { "type": ["integer", "string"], "description": "Determines the notification scheme to use. Default is None.", }, "categoryId": { "type": ["integer", "string"], "description": "Same as projectCategory. Can be used interchangeably.", }, "url": { "type": "string", "description": "A link to information about the project, such as documentation.", }, }, "required": ["key"], }, ),
• src/mcp_server_jira/jira_v3_api.py:104-175 (helper)

  Low-level helper that performs the actual HTTP request to Jira's v3 /project endpoint to create the project.
  async def create_project( self, key: str, assignee: str, name: Optional[str] = None, ptype: str = None, template_name: Optional[str] = None, avatarId: Optional[int] = None, issueSecurityScheme: Optional[int] = None, permissionScheme: Optional[int] = None, projectCategory: Optional[int] = None, notificationScheme: Optional[int] = None, categoryId: Optional[int] = None, url: str = None, ) -> Dict[str, Any]: """ Creates a new Jira project using the v3 REST API. Requires a project key and the Atlassian accountId of the project lead (`assignee`). The v3 API mandates that `leadAccountId` is always provided, regardless of default project lead settings or UI behavior. Additional project attributes such as name, type, template, avatar, schemes, category, and documentation URL can be specified. Args: key: The unique project key (required). name: The project name. Defaults to the key if not provided. assignee: Atlassian accountId of the project lead (required by v3 API). ptype: Project type key (e.g., 'software', 'business', 'service_desk'). template_name: Project template key for template-based creation. avatarId: ID of the avatar to assign to the project. issueSecurityScheme: ID of the issue security scheme. permissionScheme: ID of the permission scheme. projectCategory: ID of the project category. notificationScheme: ID of the notification scheme. categoryId: Alternative to projectCategory; preferred for v3 API. url: URL for project information or documentation. Returns: A dictionary containing details of the created project as returned by Jira. Raises: ValueError: If required parameters are missing or project creation fails. """ if not key: raise ValueError("Project key is required") if not assignee: raise ValueError( "Parameter 'assignee' (leadAccountId) is required by the Jira v3 API" ) payload = { "key": key, "name": name or key, "leadAccountId": assignee, "assigneeType": "PROJECT_LEAD", "projectTypeKey": ptype, "projectTemplateKey": template_name, "avatarId": avatarId, "issueSecurityScheme": issueSecurityScheme, "permissionScheme": permissionScheme, "notificationScheme": notificationScheme, "categoryId": categoryId or projectCategory, "url": url, } payload = {k: v for k, v in payload.items() if v is not None} print(f"Creating project with v3 API payload: {json.dumps(payload, indent=2)}") response_data = await self._make_v3_api_request( "POST", "/project", data=payload ) print(f"Project creation response: {json.dumps(response_data, indent=2)}") return response_data
• src/mcp_server_jira/server.py:96-101 (schema)

  Pydantic model defining the output structure for created projects.
  class JiraProjectResult(BaseModel): key: str name: str id: str lead: Optional[str] = None