Joplin MCP Server

Instructions

Args:
    args: Note creation parameters
        title: Note title
        body: Note content in Markdown (optional)
        parent_id: ID of parent folder (optional)
        is_todo: Whether this is a todo item (optional)

Returns:
    Dictionary containing the created note data

Implementation Reference

• src/mcp/joplin_mcp.py:129-167 (handler)

  MCP tool handler function for 'create_note', registered via @mcp.tool() decorator. Calls JoplinAPI.create_note to perform the creation.

  @mcp.tool()
  async def create_note(args: CreateNoteInput) -> Dict[str, Any]:
      """Create a new note in Joplin.
      
      Args:
          args: Note creation parameters
              title: Note title
              body: Note content in Markdown (optional)
              parent_id: ID of parent folder (optional)
              is_todo: Whether this is a todo item (optional)
      
      Returns:
          Dictionary containing the created note data
      """
      if not api:
          return {"error": "Joplin API client not initialized"}
      
      try:
          note = api.create_note(
              title=args.title,
              body=args.body,
              parent_id=args.parent_id,
              is_todo=args.is_todo
          )
          return {
              "status": "success",
              "note": {
                  "id": note.id,
                  "title": note.title,
                  "body": note.body,
                  "created_time": note.created_time.isoformat() if note.created_time else None,
                  "updated_time": note.updated_time.isoformat() if note.updated_time else None,
                  "is_todo": note.is_todo
              }
          }
      except Exception as e:
          logger.error(f"Error creating note: {e}")
          return {"error": str(e)}

• src/mcp/joplin_mcp.py:42-47 (schema)

  Pydantic input schema/model for the create_note tool parameters.

  class CreateNoteInput(BaseModel):
      """Input parameters for creating a note."""
      title: str
      body: Optional[str] = None
      parent_id: Optional[str] = None
      is_todo: Optional[bool] = False

• src/joplin/joplin_api.py:294-324 (helper)

  JoplinAPI.create_note method implementing the HTTP POST request to Joplin's /notes endpoint to create the note.

  def create_note(
      self,
      title: str,
      body: str | None = None,
      parent_id: str | None = None,
      is_todo: bool = False
  ) -> JoplinNote:
      """Create a new note.
  
      Args:
          title: Note title
          body: Note content in Markdown
          parent_id: ID of parent folder
          is_todo: Whether this is a todo item
  
      Returns:
          Created JoplinNote object
      """
      data = {
          "title": title,
          "is_todo": is_todo
      }
  
      if body is not None:
          data["body"] = body
  
      if parent_id is not None:
          data["parent_id"] = parent_id
  
      response = self._make_request("POST", "notes", json=data)
      return JoplinNote.from_api_response(response)